page.cavu.highlight

{
  "id": "page.cavu.highlight",
  "defs": {
    "main": {
      "key": "tid",
      "type": "record",
      "record": {
        "type": "object",
        "required": [
          "book",
          "document",
          "selector",
          "createdAt"
        ],
        "properties": {
          "book": {
            "type": "string",
            "format": "at-uri",
            "description": "AT-URI of the book's site.standard.publication record — the backlink target, and the key clients list by."
          },
          "note": {
            "type": "string",
            "maxLength": 10000,
            "description": "The reader's own note on the passage.",
            "maxGraphemes": 3000
          },
          "color": {
            "type": "string",
            "maxLength": 32,
            "description": "Client-chosen highlight color name or hex value. Clients without an opinion omit it."
          },
          "document": {
            "ref": "com.atproto.repo.strongRef",
            "type": "ref",
            "description": "Spine document containing the passage, at the cid the reader was seeing. A cid that no longer matches the live record marks a highlight whose ground may have shifted."
          },
          "selector": {
            "ref": "#textQuoteSelector",
            "type": "ref",
            "description": "Where in the document's text the highlight lives."
          },
          "createdAt": {
            "type": "string",
            "format": "datetime"
          },
          "thousandths": {
            "type": "integer",
            "maximum": 1000,
            "minimum": 0,
            "description": "Coarse position of the passage within the document, in thousandths of its text — page.cavu.progress's position grammar. A jump-to hint only; the selector is authoritative."
          }
        }
      },
      "description": "A reader's highlight of a passage in a book, written to the reader's own repo. The passage is anchored by text quote (exact string plus surrounding context), not by DOM position: quotes survive re-rendering, mode switches, and small edits to the chunk, and the strongRef cid marks the text *as highlighted* so drift is detectable. Selector field names and limits deliberately mirror the W3C Web Annotation TextQuoteSelector as used by at.margin.note, so a highlight translates 1:1 into a margin.at annotation target. The book AT-URI makes highlights discoverable by backlink index. Like page.cavu.progress, records are public: clients must disclose that highlights are saved to the reader's own repo."
    },
    "textQuoteSelector": {
      "type": "object",
      "required": [
        "exact"
      ],
      "properties": {
        "exact": {
          "type": "string",
          "maxLength": 5000,
          "description": "The highlighted text itself.",
          "maxGraphemes": 1500
        },
        "prefix": {
          "type": "string",
          "maxLength": 500,
          "description": "Text immediately before the quote, for disambiguating repeated passages.",
          "maxGraphemes": 150
        },
        "suffix": {
          "type": "string",
          "maxLength": 500,
          "description": "Text immediately after the quote.",
          "maxGraphemes": 150
        }
      },
      "description": "W3C Web Annotation TextQuoteSelector shape (field names and limits match at.margin.note): the exact quoted text, disambiguated by up to 150 graphemes of context on each side. Offsets are into the document's rendered text content with whitespace as rendered."
    }
  },
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1
}