Document Lexicon

The site.standard.document lexicon provides metadata for documents published on the web.

Overview

Documents may be standalone or associated with a publication. This lexicon can be used to store a document's content and its associated metadata.

Schema

Required Properties

Property	Type	Description
site	string	Points to a publication record `at://` or a publication url `https://` for loose documents. Avoid trailing slashes.
title	string	Title of the document. `maxLength: 5000` `maxGraphemes: 500`
publishedAt	datetime	Timestamp of the documents publish time.

Optional Properties Updated

Property	Type	Description
path	string	Combine with `site` or publication `url` to construct a canonical URL to the document. Prepend with a leading slash.
description	string	A brief description or excerpt from the document. `maxLength: 30000` `maxGraphemes: 3000`
coverImage	blob	Image to used for thumbnail or cover image. Less than 1MB is size.
content	union	Open union used to define the record's content. Each entry must specify a `$type` and may be extended with other lexicons to support additional content formats.
textContent	string	Plaintext representation of the documents contents. Should not contain markdown or other formatting.
bskyPostRef	ref	Strong reference to a Bluesky post. Useful to keep track of comments off-platform.
tags	array	Array of strings used to tag or categorize the document. Avoid prepending tags with hashtags. `items.maxLength: 1280` `items.maxGraphemes: 128`
links	union	Open union describing relationships between this document and external resources.
labels	union	Self-label values for this document. Effectively content warnings. (ref → `com.atproto.label.defs#selfLabels`)
contributors	array	List of additional contributors to this document (ref → #contributor).
updatedAt	datetime	Timestamp of the documents last edit.

Contributor New

The #contributor property describes a participant on a document beyond the record's author.

Property	Type	Required	Description
did	string:did	Yes	DID of the contributor.
role	string	No	Role of the contributor (ex: "editor", "translator"). `maxLength: 1000` `maxGraphemes: 100`
displayName	string	No	Optional display name override for the contributor. `maxLength: 1000` `maxGraphemes: 100`

Example

{
  "$type": "site.standard.document",
  "site": "at://did:plc:abc123/site.standard.publication/3lwafzkjqm25s",
  "path": "/blog/getting-started",
  "title": "Getting Started with Standard.site",
  "description": "Learn how to use Standard.site lexicons in your project",
  "coverImage": {
    "$type": "blob",
    "ref": {
      "$link": "bafkreiexample123456789"
    },
    "mimeType": "image/jpeg",
    "size": 245678
  },
  "textContent": "Full text of the article...",
  "tags": ["tutorial", "atproto"],
  "publishedAt": "2024-01-20T14:30:00.000Z"
}

Content Format

The content property is an open union, allowing for extensibility. Each entry must specify a $type and may be extended with other lexicons to support additional content formats like Markdown, blocks, or other rich text.

View the Lexicon

Best Practices

While we encourage avoid trailing slashes, some may not implement this in practice. If you are validating records, you should trim trailing slashes for site in your codebase.

Publication lexicon - Collections of documents
Verification - Link documents to web pages
Quick Start - Implementation guide