docs · developers

Lexicons

Two native lexicons, site.subgraph.item and site.subgraph.series. Long-form articles write site.standard.document directly; series can attach to site.standard.publication. JSON schemas are in the repo at lexicon/.

site.subgraph.item

A generic media record with a discriminated content union. Exactly one variant must be provided per record.

$type	For
`site.subgraph.item#photo`	JPEG / PNG / WebP / GIF / AVIF. Dimensions, alt text, EXIF camera metadata, BlurHash, prominent color.
`site.subgraph.item#video`	MP4 / WebM / MOV. Dimensions, duration, codec, alt text, poster frame.
`site.subgraph.item#audio`	MP3 / WAV / OGG / FLAC / M4A. Duration, codec, transcript.
`site.subgraph.item#text`	Inline short-to-medium text. `format` is `plain` or `markdown`.
`site.subgraph.item#recipe`	Structured ingredients + instructions + timing, plus prose body.
`site.subgraph.item#file`	Arbitrary file attachment. Use when no richer variant fits.

Outer fields (shared regardless of variant)

Field	Type	Required	Notes
`content`	union	yes	One of the six variants above.
`createdAt`	datetime	yes	When the record was created. ISO 8601.
`title`	string	no	Max 1000 chars.
`description`	string	no	Max 10000. Plain or markdown.
`tags`	string[]	no	Max 50. Mirrors `site.standard.document.tags`.
`capturedAt`	datetime	no	When the underlying content was captured/authored.
`location`	#geoLocation	no	GPS. Opt-in only — publish with consent.
`series`	at-uri	no	AT-URI of a `site.subgraph.series`.

site.subgraph.series

A named, standalone collection of items. Items reference a series by AT-URI via their series field. A document can embed a series inline via site.subgraph.content.seriesEmbed.

Field	Type	Required	Notes
`title`	string	yes	Max 1000.
`createdAt`	datetime	yes	ISO 8601.
`description`	string	no	Max 10000.

site.subgraph.content.seriesEmbed

Content block embedded in site.standard.document.content[] to inline a series. Same role as site.subgraph.content.recipe — documents name what goes inline; the series stays a first-class standalone record.

Field	Type	Required	Notes
`series`	at-uri	yes	AT-URI of the `site.subgraph.series`.
`title`	string	no	Display override for this embed context.
`note`	string	no	Lead-in / caption paragraph rendered above the items.
`layout`	string	no	Hint: `grid` · `stack` · `gallery` · `film`.
`maxItems`	integer	no	Cap on inline-rendered items; pair with a "see full series" link.

Extension of site.standard.*

Subgraph uses the canonical Standard.site lexicons for long-form content:

site.standard.document — articles. The app and CLI write this directly; there is no site.subgraph.item#article variant. Body, cover image, tags, publishedAt, and an open content[] block array (recipes, series embeds, anything with a $type).
site.standard.publication — a themed, URL-rooted container that groups documents. Documents reference a publication via their site field.

Anything that already reads site.standard.* reads the long-form side of subgraph for free. Series embeds are the seam: renderers that recognize site.subgraph.content.seriesEmbed inline the collection; renderers that don't fall back to a link.

Authority (DNS TXT)

Per lexicon.garden, resolving site.subgraph.* via the registry requires a DNS TXT record at _lexicon.subgraph.site pointing to the publishing DID:

_lexicon.subgraph.site  TXT  did=did:plc:...

Until that's set, consume the JSON schemas directly from the repo at lexicon/.

Example

A photo item in a series, then a document that embeds the series inline:

// at://did:plc:abc/site.subgraph.series/3k2b
{
  "$type": "site.subgraph.series",
  "title": "Joshua Tree, Spring 2026",
  "createdAt": "2026-04-15T00:00:00Z"
}

// at://did:plc:abc/site.subgraph.item/3k3c
{
  "$type": "site.subgraph.item",
  "content": {
    "$type": "site.subgraph.item#photo",
    "blob": { "$type": "blob", "ref": { "$link": "bafkrei..." },
              "mimeType": "image/jpeg", "size": 2458624 },
    "dimensions": { "width": 4096, "height": 2731 },
    "alt": "Night sky over Joshua Tree.",
    "prominentColor": "#1a1832"
  },
  "title": "Orion rising",
  "series": "at://did:plc:abc/site.subgraph.series/3k2b",
  "capturedAt": "2026-04-11T04:36:41Z",
  "createdAt": "2026-04-15T21:30:00Z"
}

// at://did:plc:abc/site.standard.document/3k4d
{
  "$type": "site.standard.document",
  "site": "at://did:plc:abc/site.standard.publication/3k1a",
  "title": "Notes from Joshua Tree",
  "publishedAt": "2026-04-16T10:00:00Z",
  "content": [
    {
      "$type": "site.subgraph.content.seriesEmbed",
      "series": "at://did:plc:abc/site.subgraph.series/3k2b",
      "note": "The whole set — click through for the full resolution.",
      "layout": "gallery",
      "maxItems": 6
    }
  ]
}