The GoBrief Brief Format.
A brief is a portable, spec-declared, verifiable collection or delivery event between two parties. This page documents the open data format so any tool can read, write, and verify briefs that travel beyond GoBrief itself.
Why open
Getting things from people, and delivering things to people, is fundamentally a two-party protocol. If the data format is locked to one vendor, the protocol breaks the moment one side switches tools. GoBrief publishes the format so the artifact outlives the tool: a competitor can implement the same schema and their briefs remain verifiable against our endpoint. That is the point.
The format is dedicated to the public domain (CC0-1.0). No patent claims, no royalties, no sign-up, no attribution required.
Discovery
The discovery document lives at /.well-known/gobrief-spec.json. Fetch it once to learn the current version, the human docs URL, the verification endpoint, and the inline JSON Schema.
$ curl -s https://gobrief.co/.well-known/gobrief-spec.json | jq '.version' "1.0.0"
A minimal brief
Every brief is a JSON object with a format, a direction, a sender, and at least one placement. Here is a complete COLLECT brief with the full privacy posture declared:
{
"format": "gobrief.brief",
"version": "1.0.0",
"id": "br_3k2n7p9r",
"direction": "collect",
"name": "Jade Harlow: Press Photo Pack",
"description": "Three press photos for the release cycle. Horizontal + vertical + square crops.",
"sender": {
"name": "Riverline Records",
"domain": "riverline.fm",
"contactEmail": "press@riverline.fm"
},
"recipient": {
"name": "Jade Harlow",
"email": "jade@example.com"
},
"placements": [
{
"id": "press-horizontal",
"name": "Horizontal press photo",
"mediaType": "image",
"specHuman": "3000 x 2000 px · horizontal · JPG or PNG · up to 30 MB",
"spec": {
"mediaType": "image",
"minWidth": 3000,
"minHeight": 2000,
"orientation": "horizontal",
"formats": [
"image/jpeg",
"image/png"
],
"maxSizeMb": 30
},
"required": true
}
],
"deadline": "2026-07-01T23:59:00Z",
"privacy": {
"aiTraining": false,
"trackingPixels": false,
"marketingEmail": false,
"pullbackHours": 24,
"retentionAfterCloseDays": 30
},
"links": {
"canonical": "https://gobrief.co/b/abc123xyz",
"publicStatus": "https://gobrief.co/status/ps_abc123"
},
"signature": {
"alg": "HS256",
"keyId": "gb-sign-2026",
"value": "eyJhbGciOi…"
}
}Direction, collect vs deliver
Two directions are supported:
collect, the sender is asking the recipient to upload assets. The brief describes what is needed and carries the spec for each placement.deliver, the sender is handing assets to the recipient (press kit, final deliverable, press embargo packet). The brief references items the sender has already approved.
Every canonical GoBrief URL takes the form https://gobrief.co/b/<token>. The token resolves to an intake or delivery surface depending on direction.
Privacy posture is machine-readable
The privacy object lets an implementation tell the recipient, in a structured way, exactly how their data will be treated. GoBrief surfaces these fields as the anti-features row on every intake page (no AI training, no tracking pixels, no marketing email, documented pullback window, documented retention). Any tool implementing the format is encouraged to do the same.
Signatures
An optional signature field carries a detached JWS signature over the canonical JSON of the brief (excluding the signature field itself). Supported algorithms: HS256, RS256, ES256. Key material is managed by the signer; GoBrief publishes its own public keys at /.well-known/gobrief-spec.json (forthcoming).
Verification
Post a brief JSON to the verify endpoint to have its schema conformance and, where present, its signature checked:
POST https://gobrief.co/api/spec/verify Content-Type: application/json <brief-json>
Response is a small JSON object: { ok: true | false, errors: [...] }. Implementations may run their own local verification against the schema and skip the round-trip; the endpoint exists so clients that don't ship a JSON Schema validator can still validate.
JSON Schema
Inline for convenience. The same document is served at the discovery URL withAccess-Control-Allow-Origin: * so a browser-based validator can fetch it directly.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://gobrief.co/.well-known/gobrief-spec.json",
"title": "GoBrief Brief",
"description": "A portable representation of a GoBrief brief: a verified, signed, spec-declared collection or delivery between two parties.",
"type": "object",
"required": [
"format",
"version",
"id",
"direction",
"sender",
"placements"
],
"additionalProperties": false,
"properties": {
"format": {
"const": "gobrief.brief",
"description": "Literal identifier. Must equal \"gobrief.brief\" to be treated as a spec-compliant brief."
},
"version": {
"type": "string",
"description": "Semantic version of the GoBrief Brief Format used.",
"examples": [
"1.0.0"
]
},
"id": {
"type": "string",
"description": "Opaque, globally unique identifier for this brief. Not a URL; use `links.canonical` for the human-shareable URL.",
"minLength": 1
},
"direction": {
"type": "string",
"enum": [
"collect",
"deliver"
],
"description": "Whether the brief collects assets from the recipient (collect) or delivers assets to the recipient (deliver)."
},
"name": {
"type": "string",
"description": "Human-readable brief title. Max 120 characters.",
"maxLength": 120
},
"description": {
"type": "string",
"description": "Optional one-paragraph context. Max 1000 characters.",
"maxLength": 1000
},
"sender": {
"type": "object",
"required": [
"name"
],
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "Display name of the sending organization."
},
"domain": {
"type": "string",
"description": "DNS-verifiable domain of the sender, if any."
},
"contactEmail": {
"type": "string",
"format": "email"
}
}
},
"recipient": {
"type": "object",
"description": "The party the brief is scoped to. Omitted for multi-recipient public status artifacts.",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"org": {
"type": "string"
}
}
},
"placements": {
"type": "array",
"description": "The list of things to collect or deliver. One entry per asset.",
"minItems": 1,
"items": {
"type": "object",
"required": [
"id",
"name",
"mediaType"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"mediaType": {
"type": "string",
"enum": [
"image",
"vector",
"video",
"audio",
"text",
"pdf",
"bundle"
]
},
"specHuman": {
"type": "string",
"description": "Plain-English specification, e.g. \"8.5 x 11 in PDF, CMYK, 300 dpi, 50 MB max\"."
},
"spec": {
"type": "object",
"description": "Machine-readable specification. Implementations SHOULD validate uploads against these fields before transmitting.",
"additionalProperties": true,
"properties": {
"mediaType": {
"type": "string",
"enum": [
"image",
"vector",
"video",
"audio",
"text",
"pdf",
"bundle"
]
},
"width": {
"type": "number"
},
"height": {
"type": "number"
},
"minWidth": {
"type": "number"
},
"minHeight": {
"type": "number"
},
"dpi": {
"type": "number"
},
"minDpi": {
"type": "number"
},
"colorSpace": {
"type": "string",
"enum": [
"RGB",
"CMYK",
"grayscale"
]
},
"formats": {
"type": "array",
"items": {
"type": "string"
}
},
"maxSizeMb": {
"type": "number"
},
"minDurationSec": {
"type": "number"
},
"maxDurationSec": {
"type": "number"
},
"orientation": {
"type": "string",
"enum": [
"horizontal",
"vertical",
"square"
]
},
"aspectRatio": {
"type": "number"
},
"maxCharacters": {
"type": "number"
},
"requireVector": {
"type": "boolean"
},
"trimWidth": {
"type": "number"
},
"trimHeight": {
"type": "number"
}
}
},
"required": {
"type": "boolean",
"description": "Whether this placement is required to complete the brief.",
"default": true
}
}
}
},
"deadline": {
"type": "string",
"format": "date-time",
"description": "Optional ISO 8601 deadline for completion."
},
"embargo": {
"type": "object",
"description": "Optional publication embargo, used primarily for DELIVER briefs.",
"additionalProperties": false,
"properties": {
"liftsAt": {
"type": "string",
"format": "date-time"
},
"note": {
"type": "string"
}
}
},
"privacy": {
"type": "object",
"description": "Machine-readable privacy posture. Implementations SHOULD surface these to recipients before upload.",
"additionalProperties": false,
"properties": {
"aiTraining": {
"type": "boolean",
"description": "Whether uploads may be used to train AI models.",
"default": false
},
"trackingPixels": {
"type": "boolean",
"description": "Whether the intake surface loads third-party tracking pixels.",
"default": false
},
"marketingEmail": {
"type": "boolean",
"description": "Whether the sender will send unsolicited marketing email to the recipient.",
"default": false
},
"pullbackHours": {
"type": "number",
"description": "How many hours the recipient has to withdraw an upload after submission. 0 = no pullback.",
"minimum": 0
},
"retentionAfterCloseDays": {
"type": "number",
"description": "How many days uploads are retained after the brief is closed. 0 = deleted immediately.",
"minimum": 0
}
}
},
"links": {
"type": "object",
"description": "Canonical and alternate URLs for this brief.",
"additionalProperties": false,
"required": [
"canonical"
],
"properties": {
"canonical": {
"type": "string",
"format": "uri",
"description": "The canonical GoBrief short-link. SHOULD take the form https://<host>/b/<token>."
},
"publicStatus": {
"type": "string",
"format": "uri",
"description": "If the sender has enabled a public status artifact, the URL for it."
}
}
},
"signature": {
"type": "object",
"description": "Optional detached signature over the canonical JSON representation of this object (excluding this field). Implementations SHOULD verify.",
"additionalProperties": false,
"required": [
"alg",
"value"
],
"properties": {
"alg": {
"type": "string",
"enum": [
"HS256",
"RS256",
"ES256"
]
},
"keyId": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
}Versioning
Semantic versioning. Minor versions add optional fields without breaking existing implementations. Major versions are reserved for breaking changes and will be announced at least 90 days in advance via this page and the RSS feed at /spec/rss.xml (forthcoming). Current version: 1.0.0.
Contact
Spec questions, implementation notes, and PRs: spec@gobrief.co.