Developer docs

Lexicons

Published AT Proto record schemas for reader state in each user's PDS.

Overview

Standard Reader owns the app.standard-reader.* namespace. These lexicons describe repo records — bookmarks, read state, lists, and related shared definitions. AppView XRPC queries and procedures are documented on /docs/api.

Namespace

Authority for app.standard-reader resolves via DNS _lexicon.* TXT records to the publishing account.

Shared definitions

defs · 1 schema

app.standard-reader.defsdefs

9 shared schema definitions for AppView responses and unions.

Definitions

Name	Type
publicationView	object
documentView	object
profileView	object
cursorPagePublications	object
cursorPageDocuments	object
resolveViewArticle	object
resolveViewPublication	object
resolveViewReaderLink	object
resolveViewUnknown	object

schema

{
  "lexicon": 1,
  "id": "app.standard-reader.defs",
  "defs": {
    "publicationView": {
      "type": "object",
      "description": "A publication as shown in directory cards and profile headers.",
      "required": [
        "uri",
        "did",
        "name",
        "url",
        "subscriberCount",
        "documentCount"
      ],
      "properties": {
        "uri": {
          "type": "string",
          "format": "at-uri"
        },
        "did": {
          "type": "string",
          "format": "did"
        },
        "name": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "description": {
          "type": "string",
          "nullable": true
        },
        "iconUrl": {
          "type": "string",
          "format": "uri",
          "nullable": true
        },
        "ownerAvatarUrl": {
          "type": "string",
          "format": "uri",
          "nullable": true
        },
        "ownerHandle": {
          "type": "string",
          "nullable": true
        },
        "topic": {
          "type": "string",
          "nullable": true
        },
        "verified": {
          "type": "boolean"
        },
        "subscriberCount": {
          "type": "integer"
        },
        "documentCount": {
          "type": "integer"
        },
        "lastDocumentAt": {
          "type": "string",
          "format": "datetime",
          "nullable": true
        },
        "searchNameHtml": {
          "type": "string",
          "nullable": true
        },
        "searchSnippetHtml": {
          "type": "string",
          "nullable": true
        }
      }
    },
    "documentView": {
      "type": "object",
      "description": "An article as shown in feed rows and search results (metadata only).",
      "required": [
        "uri",
        "did",
        "title",
        "publishedAt",
        "recommendCount",
        "commentCount",
        "hasRenderableBody",
        "isRead"
      ],
      "properties": {
        "uri": {
          "type": "string",
          "format": "at-uri"
        },
        "did": {
          "type": "string",
          "format": "did"
        },
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string",
          "nullable": true
        },
        "path": {
          "type": "string",
          "nullable": true
        },
        "canonicalUrl": {
          "type": "string",
          "format": "uri",
          "nullable": true
        },
        "coverImageUrl": {
          "type": "string",
          "format": "uri",
          "nullable": true
        },
        "publishedAt": {
          "type": "string",
          "format": "datetime"
        },
        "featured": {
          "type": "boolean"
        },
        "publicationUri": {
          "type": "string",
          "format": "at-uri",
          "nullable": true
        },
        "publicationName": {
          "type": "string",
          "nullable": true
        },
        "publicationIconUrl": {
          "type": "string",
          "format": "uri",
          "nullable": true
        },
        "publicationOwnerAvatarUrl": {
          "type": "string",
          "format": "uri",
          "nullable": true
        },
        "publicationOwnerHandle": {
          "type": "string",
          "nullable": true
        },
        "publicationBannerUrl": {
          "type": "string",
          "format": "uri",
          "nullable": true
        },
        "publicationTopic": {
          "type": "string",
          "nullable": true
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "nullable": true
        },
        "recommendCount": {
          "type": "integer"
        },
        "commentCount": {
          "type": "integer"
        },
        "hasRenderableBody": {
          "type": "boolean"
        },
        "isRead": {
          "type": "boolean"
        },
        "searchTitleHtml": {
          "type": "string",
          "nullable": true
        },
        "searchSnippetHtml": {
          "type": "string",
          "nullable": true
        }
      }
    },
    "profileView": {
      "type": "object",
      "required": [
        "did"
      ],
      "properties": {
        "did": {
          "type": "string",
          "format": "did"
        },
        "handle": {
          "type": "string",
          "nullable": true
        },
        "displayName": {
          "type": "string",
          "nullable": true
        },
        "description": {
          "type": "string",
          "nullable": true
        },
        "avatarUrl": {
          "type": "string",
          "format": "uri",
          "nullable": true
        },
        "bannerUrl": {
          "type": "string",
          "format": "uri",
          "nullable": true
        }
      }
    },
    "cursorPagePublications": {
      "type": "object",
      "required": [
        "items"
      ],
      "properties": {
        "cursor": {
          "type": "string",
          "nullable": true
        },
        "items": {
          "type": "array",
          "items": {
            "type": "ref",
            "ref": "app.standard-reader.defs#publicationView"
          }
        }
      }
    },
    "cursorPageDocuments": {
      "type": "object",
      "required": [
        "items"
      ],
      "properties": {
        "cursor": {
          "type": "string",
          "nullable": true
        },
        "items": {
          "type": "array",
          "items": {
            "type": "ref",
            "ref": "app.standard-reader.defs#documentView"
          }
        }
      }
    },
    "resolveViewArticle": {
      "type": "object",
      "required": [
        "kind",
        "documentUri",
        "title",
        "readerUrl",
        "recommendCount",
        "commentCount"
      ],
      "properties": {
        "kind": {
          "type": "string",
          "const": "article"
        },
        "documentUri": {
          "type": "string",
          "format": "at-uri"
        },
        "title": {
          "type": "string"
        },
        "publicationUri": {
          "type": "string",
          "format": "at-uri",
          "nullable": true
        },
        "publicationName": {
          "type": "string",
          "nullable": true
        },
        "publicationHandle": {
          "type": "string",
          "nullable": true
        },
        "publicationIconUrl": {
          "type": "string",
          "format": "uri",
          "nullable": true
        },
        "publicationOwnerAvatarUrl": {
          "type": "string",
          "format": "uri",
          "nullable": true
        },
        "publicationSubscriberCount": {
          "type": "integer",
          "nullable": true
        },
        "publicationReaderUrl": {
          "type": "string",
          "format": "uri",
          "nullable": true
        },
        "publishedAt": {
          "type": "string",
          "format": "datetime",
          "nullable": true
        },
        "readingMinutes": {
          "type": "integer",
          "nullable": true
        },
        "authorName": {
          "type": "string",
          "nullable": true
        },
        "authorHandle": {
          "type": "string",
          "nullable": true
        },
        "authorAvatarUrl": {
          "type": "string",
          "format": "uri",
          "nullable": true
        },
        "readerUrl": {
          "type": "string",
          "format": "uri"
        },
        "canonicalUrl": {
          "type": "string",
          "format": "uri",
          "nullable": true
        },
        "isBookmarked": {
          "type": "boolean"
        },
        "isRead": {
          "type": "boolean"
        },
        "isFollowing": {
          "type": "boolean"
        },
        "recommendCount": {
          "type": "integer"
        },
        "commentCount": {
          "type": "integer"
        }
      }
    },
    "resolveViewPublication": {
      "type": "object",
      "required": [
        "kind",
        "publicationUri",
        "name",
        "readerUrl"
      ],
      "properties": {
        "kind": {
          "type": "string",
          "const": "publication"
        },
        "publicationUri": {
          "type": "string",
          "format": "at-uri"
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": "string",
          "nullable": true
        },
        "handle": {
          "type": "string",
          "nullable": true
        },
        "iconUrl": {
          "type": "string",
          "format": "uri",
          "nullable": true
        },
        "ownerAvatarUrl": {
          "type": "string",
          "format": "uri",
          "nullable": true
        },
        "subscriberCount": {
          "type": "integer",
          "nullable": true
        },
        "readerUrl": {
          "type": "string",
          "format": "uri"
        },
        "siteUrl": {
          "type": "string",
          "format": "uri",
          "nullable": true
        },
        "isFollowing": {
          "type": "boolean"
        }
      }
    },
    "resolveViewReaderLink": {
      "type": "object",
      "required": [
        "kind",
        "readerUrl"
      ],
      "properties": {
        "kind": {
          "type": "string",
          "const": "reader-link"
        },
        "readerUrl": {
          "type": "string"
        }
      }
    },
    "resolveViewUnknown": {
      "type": "object",
      "required": [
        "kind"
      ],
      "properties": {
        "kind": {
          "type": "string",
          "const": "unknown"
        }
      }
    }
  }
}

Records

PDS records · 4 schemas

app.standard-reader.bookmarkrecordkey: any

Marks a site.standard.document as saved for later by the reader. Presence of the record means saved; deleting it removes the article from the save queue.

Fields

Name	Type
subject*AT URI of the site.standard.document record to save.	string · at-uri
createdAt*When the reader saved the article.	string · datetime

schema

{
  "lexicon": 1,
  "id": "app.standard-reader.bookmark",
  "defs": {
    "main": {
      "type": "record",
      "description": "Marks a site.standard.document as saved for later by the reader. Presence of the record means saved; deleting it removes the article from the save queue.",
      "key": "any",
      "record": {
        "type": "object",
        "required": [
          "subject",
          "createdAt"
        ],
        "properties": {
          "subject": {
            "type": "string",
            "format": "at-uri",
            "description": "AT URI of the site.standard.document record to save."
          },
          "createdAt": {
            "type": "string",
            "format": "datetime",
            "description": "When the reader saved the article."
          }
        }
      }
    }
  }
}

app.standard-reader.listrecordkey: tid

A named, ordered, shareable list of publications (like a Bluesky user list, but for site.standard.publication subscriptions). Lists are one level deep; a publication may appear in multiple lists.

Fields

Name	Type
name*Display name of the list.	string
descriptionOptional description shown on the list's public page.	string
publications*Ordered AT URIs of the site.standard.publication records in this list.	at-uri[]
createdAt*When the list was created.	string · datetime

schema

{
  "lexicon": 1,
  "id": "app.standard-reader.list",
  "defs": {
    "main": {
      "type": "record",
      "description": "A named, ordered, shareable list of publications (like a Bluesky user list, but for site.standard.publication subscriptions). Lists are one level deep; a publication may appear in multiple lists.",
      "key": "tid",
      "record": {
        "type": "object",
        "required": [
          "name",
          "publications",
          "createdAt"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 640,
            "maxGraphemes": 64,
            "description": "Display name of the list."
          },
          "description": {
            "type": "string",
            "maxLength": 3000,
            "maxGraphemes": 300,
            "description": "Optional description shown on the list's public page."
          },
          "publications": {
            "type": "array",
            "maxLength": 500,
            "items": {
              "type": "string",
              "format": "at-uri"
            },
            "description": "Ordered AT URIs of the site.standard.publication records in this list."
          },
          "createdAt": {
            "type": "string",
            "format": "datetime",
            "description": "When the list was created."
          }
        }
      }
    }
  }
}

app.standard-reader.listSaverecordkey: any

Saves another reader's app.standard-reader.list into this reader's app (like adding a Bluesky list). Presence of the record means saved; deleting it removes the list again.

Fields

Name	Type
list*AT URI of the app.standard-reader.list record being saved.	string · at-uri
createdAt*When the list was saved.	string · datetime

schema

{
  "lexicon": 1,
  "id": "app.standard-reader.listSave",
  "defs": {
    "main": {
      "type": "record",
      "description": "Saves another reader's app.standard-reader.list into this reader's app (like adding a Bluesky list). Presence of the record means saved; deleting it removes the list again.",
      "key": "any",
      "record": {
        "type": "object",
        "required": [
          "list",
          "createdAt"
        ],
        "properties": {
          "list": {
            "type": "string",
            "format": "at-uri",
            "description": "AT URI of the app.standard-reader.list record being saved."
          },
          "createdAt": {
            "type": "string",
            "format": "datetime",
            "description": "When the list was saved."
          }
        }
      }
    }
  }
}

app.standard-reader.readrecordkey: any

Marks a site.standard.document as read by the reader. Presence of the record means read; deleting it marks the article unread again.

Fields

Name	Type
subject*AT URI of the site.standard.document record that was read.	string · at-uri
createdAt*When the reader opened / marked the article read.	string · datetime

schema

{
  "lexicon": 1,
  "id": "app.standard-reader.read",
  "defs": {
    "main": {
      "type": "record",
      "description": "Marks a site.standard.document as read by the reader. Presence of the record means read; deleting it marks the article unread again.",
      "key": "any",
      "record": {
        "type": "object",
        "required": [
          "subject",
          "createdAt"
        ],
        "properties": {
          "subject": {
            "type": "string",
            "format": "at-uri",
            "description": "AT URI of the site.standard.document record that was read."
          },
          "createdAt": {
            "type": "string",
            "format": "datetime",
            "description": "When the reader opened / marked the article read."
          }
        }
      }
    }
  }
}