docs · developers

Lexicons

Every subgraph publish writes a site.subgraph.item record. The item is the chronological feed anchor; its content field is an open union of content-block lexicons. The same content blocks plug into site.standard.document.content[], so long-form composed content uses the same primitives.

Shape

FEED ANCHOR
  site.subgraph.item
    content: open union of:
      site.subgraph.content.photo
      site.subgraph.content.video
      site.subgraph.content.audio
      site.subgraph.content.text
      site.subgraph.content.file
      site.subgraph.content.recipe
      site.subgraph.content.documentRef   → site.standard.document
      site.subgraph.content.seriesRef     → site.subgraph.series
    series?:      at-uri (membership in a series)
    publication?: at-uri (advisory: canonical website home)

TOP-LEVEL RECORDS that items can reference
  site.standard.document
    content[]: same content blocks (+ seriesEmbed for inline collections)
    site: at-uri (→ publication)

  site.subgraph.series
    publication?: at-uri (advisory)

CONTAINER
  site.standard.publication
    url, name, description, icon

site.subgraph.item

Chronological feed anchor. One record per publish.

Field	Type	Required	Notes
`content`	open union	yes	One content-block payload. See the blocks below.
`createdAt`	datetime	yes	ISO 8601. Feed sort key.
`title`	string	no	Max 1000.
`description`	string	no	Max 10000. Plain or markdown. This is where recipe prose goes.
`tags`	string[]	no	Max 50. Mirrors `site.standard.document.tags`.
`capturedAt`	datetime	no	When the underlying content was captured/authored.
`location`	ref (geoLocation)	no	GPS. Publish only with consent.
`series`	at-uri	no	AT-URI of a `site.subgraph.series` this item is a MEMBER of.
`publication`	at-uri	no	Advisory: AT-URI of the `site.standard.publication` this item's canonical web home is on. Not ownership — a renderer hint. Items can have zero, one, or be referenced by multiple sites.

Content blocks

Each block is its own lexicon. The same block definition slots into site.subgraph.item.content (as a feed entry's payload) AND site.standard.document.content[] (as an inline block in long-form). One shape, two wrappers.

Block ($type)	For
`site.subgraph.content.photo`	Image blob + dimensions, alt, EXIF camera, BlurHash, prominent color.
`site.subgraph.content.video`	Video blob + dimensions, duration, poster, codec, alt.
`site.subgraph.content.audio`	Audio blob + duration, codec, transcript.
`site.subgraph.content.text`	Short/medium text. Plain or markdown.
`site.subgraph.content.file`	Arbitrary file attachment + MIME type + filename.
`site.subgraph.content.recipe`	Structured ingredients, instructions, timing, source, equipment. Prose body lives on the wrapping `item.description`, not here.
`site.subgraph.content.documentRef`	Points an item at a `site.standard.document`. Use when the real payload is long-form; the item is the feed anchor. Optional cached `title`/`excerpt`/`coverImage` for preview without fetching.
`site.subgraph.content.seriesRef`	Points an item at a `site.subgraph.series`. Use when the feed entry IS a series (a post announcing a collection). Distinct from `seriesEmbed`, which lives inside documents to inline a series's items.

site.subgraph.series

Standalone named collection. Items reference it via their series field.

Field	Type	Required	Notes
`title`	string	yes	Max 1000.
`createdAt`	datetime	yes	ISO 8601.
`description`	string	no	Max 10000.
`publication`	at-uri	no	Advisory publication reference, same semantics as on `item`.

site.subgraph.content.seriesEmbed (document-only)

Content block embedded in site.standard.document.content[] to inline a series. Distinct from seriesRef, which is used at the item level. Renderer sees this block, fetches the series, renders member items with the block's layout hint.

Field	Type	Required	Notes
`series`	at-uri	yes	AT-URI of the series.
`title`	string	no	Display override for this embed.
`note`	string	no	Lead-in / caption paragraph.
`layout`	string	no	`grid` · `stack` · `gallery` · `film`.
`maxItems`	integer	no	Cap on inline-rendered items.

Reading the feed

A content-agnostic chronological feed is a single listRecords query against the site.subgraph.item collection on a user's PDS, sorted by createdAt. Each record's content.$type tells the renderer how to draw it. If publication is set, renderers scoped to a particular site (photos.example.com, recipes.example.com) filter to matching URIs.

Long-form articles live in the site.standard.document collection. An item with a documentRef content block points at one. Renderers can follow the ref or rely on the cached preview fields.

Extension of site.standard.*

site.standard.document — long-form article. Its content[] is an open union; subgraph content blocks plug in directly. Anything that already reads site.standard.* renders subgraph-composed documents without adaptation.
site.standard.publication — site container. Owns documents via their site field. Items and series reference publications advisorily; they're not owned. A user can run many publications.

Authority (DNS TXT)

Per lexicon.garden, resolving site.subgraph.* 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 lexicon/ directory in the repo.

Example

A photo item in a series, claiming a publication as its canonical home:

{
  "$type": "site.subgraph.item",
  "content": {
    "$type": "site.subgraph.content.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",
  "publication": "at://did:plc:abc/site.standard.publication/3k1a",
  "capturedAt": "2026-04-11T04:36:41Z",
  "createdAt": "2026-04-15T21:30:00Z"
}

A long-form article as a document with subgraph content blocks:

// 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.text",
      "body": "Four days in the desert. Cold at night...",
      "format": "markdown" },
    { "$type": "site.subgraph.content.seriesEmbed",
      "series": "at://did:plc:abc/site.subgraph.series/3k2b",
      "note": "The whole set.",
      "layout": "gallery",
      "maxItems": 6 }
  ]
}

// Feed anchor — an item with a documentRef to the document above
// at://did:plc:abc/site.subgraph.item/3k4e
{
  "$type": "site.subgraph.item",
  "content": {
    "$type": "site.subgraph.content.documentRef",
    "document": "at://did:plc:abc/site.standard.document/3k4d",
    "title": "Notes from Joshua Tree",
    "excerpt": "Four days in the desert..."
  },
  "publication": "at://did:plc:abc/site.standard.publication/3k1a",
  "createdAt": "2026-04-16T10:00:00Z"
}