at.margin.note

margin.at

Documentation

A W3C-compliant web annotation stored on the AT Protocol

main record

A W3C-compliant web annotation stored on the AT Protocol

Record Key tid Timestamp-based ID

Properties

body ref #body Optional

The annotation content (text or reference). For bookmarks, use body.value for the description.

color string Optional

Highlight color tint

maxLength: 20 bytes

createdAt string datetime Required

An RFC 3339 formatted timestamp.

facets array of ref app.bsky.richtext.facet Optional

Rich text facets (e.g. mentions, links)

generator ref #generator Optional

The client/agent that created this record

labels ref com.atproto.label.defs#selfLabels Optional

Self-applied content labels for this annotation

modifiedAt string datetime Optional

When this record was last modified

motivation string Required

W3C motivation for the annotation

Known values: commenting, highlighting, bookmarking, tagging, describing, linking, replying, editing, questioning, assessing

rights string uri Optional

License URI (e.g., https://creativecommons.org/licenses/by/4.0/)

tags array of string Optional

Tags for categorization

maxLength: 10 items

target ref #target Required

The resource being annotated with optional selector

View raw schema

{
  "key": "tid",
  "type": "record",
  "record": {
    "type": "object",
    "required": [
      "motivation",
      "target",
      "createdAt"
    ],
    "properties": {
      "body": {
        "ref": "#body",
        "type": "ref",
        "description": "The annotation content (text or reference). For bookmarks, use body.value for the description."
      },
      "tags": {
        "type": "array",
        "items": {
          "type": "string",
          "maxLength": 64,
          "maxGraphemes": 32
        },
        "maxLength": 10,
        "description": "Tags for categorization"
      },
      "color": {
        "type": "string",
        "maxLength": 20,
        "description": "Highlight color tint"
      },
      "facets": {
        "type": "array",
        "items": {
          "ref": "app.bsky.richtext.facet",
          "type": "ref"
        },
        "description": "Rich text facets (e.g. mentions, links)"
      },
      "labels": {
        "ref": "com.atproto.label.defs#selfLabels",
        "type": "ref",
        "description": "Self-applied content labels for this annotation"
      },
      "rights": {
        "type": "string",
        "format": "uri",
        "description": "License URI (e.g., https://creativecommons.org/licenses/by/4.0/)"
      },
      "target": {
        "ref": "#target",
        "type": "ref",
        "description": "The resource being annotated with optional selector"
      },
      "createdAt": {
        "type": "string",
        "format": "datetime"
      },
      "generator": {
        "ref": "#generator",
        "type": "ref",
        "description": "The client/agent that created this record"
      },
      "modifiedAt": {
        "type": "string",
        "format": "datetime",
        "description": "When this record was last modified"
      },
      "motivation": {
        "type": "string",
        "description": "W3C motivation for the annotation",
        "knownValues": [
          "commenting",
          "highlighting",
          "bookmarking",
          "tagging",
          "describing",
          "linking",
          "replying",
          "editing",
          "questioning",
          "assessing"
        ]
      }
    }
  },
  "description": "A W3C-compliant web annotation stored on the AT Protocol"
}

body object

Annotation body - the content of the annotation

Properties

format string Optional

MIME type of the body content

uri string uri Optional

Reference to external body content

value string Optional

Text content of the annotation. For bookmarks, this is the description.

maxLength: 10000 bytesmaxGraphemes: 3000 graphemes

View raw schema

{
  "type": "object",
  "properties": {
    "uri": {
      "type": "string",
      "format": "uri",
      "description": "Reference to external body content"
    },
    "value": {
      "type": "string",
      "maxLength": 10000,
      "description": "Text content of the annotation. For bookmarks, this is the description.",
      "maxGraphemes": 3000
    },
    "format": {
      "type": "string",
      "default": "text/plain",
      "description": "MIME type of the body content"
    }
  },
  "description": "Annotation body - the content of the annotation"
}

generator object

The client/agent that created this record

Properties

homepage string uri Optional

A valid URI.

id string uri Optional

A valid URI.

name string Optional

No description available.

View raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uri"
    },
    "name": {
      "type": "string"
    },
    "homepage": {
      "type": "string",
      "format": "uri"
    }
  },
  "description": "The client/agent that created this record"
}

selector object

W3C Web Annotation Selector. The 'type' field discriminates the selector kind using W3C type names (e.g. TextQuoteSelector). This follows W3C conventions, not ATProto union $type.

Properties

conformsTo string uri Optional

FragmentSelector: URI of the specification the fragment conforms to

end integer Optional

TextPositionSelector: end character offset (exclusive)

minimum: 0

exact string Optional

TextQuoteSelector: the exact text being selected

maxLength: 5000 bytesmaxGraphemes: 1500 graphemes

prefix string Optional

TextQuoteSelector: text immediately before the selection, for disambiguation

maxLength: 500 bytesmaxGraphemes: 150 graphemes

start integer Optional

TextPositionSelector: start character offset (inclusive)

minimum: 0

suffix string Optional

TextQuoteSelector: text immediately after the selection, for disambiguation

maxLength: 500 bytesmaxGraphemes: 150 graphemes

type string Required

W3C selector type identifier

Known values: TextQuoteSelector, TextPositionSelector, CssSelector, XPathSelector, FragmentSelector, RangeSelector

value string Optional

CssSelector/XPathSelector/FragmentSelector: the selector expression or fragment value

maxLength: 2000 bytes

View raw schema

{
  "type": "object",
  "required": [
    "type"
  ],
  "properties": {
    "end": {
      "type": "integer",
      "minimum": 0,
      "description": "TextPositionSelector: end character offset (exclusive)"
    },
    "type": {
      "type": "string",
      "description": "W3C selector type identifier",
      "knownValues": [
        "TextQuoteSelector",
        "TextPositionSelector",
        "CssSelector",
        "XPathSelector",
        "FragmentSelector",
        "RangeSelector"
      ]
    },
    "exact": {
      "type": "string",
      "maxLength": 5000,
      "description": "TextQuoteSelector: the exact text being selected",
      "maxGraphemes": 1500
    },
    "start": {
      "type": "integer",
      "minimum": 0,
      "description": "TextPositionSelector: start character offset (inclusive)"
    },
    "value": {
      "type": "string",
      "maxLength": 2000,
      "description": "CssSelector/XPathSelector/FragmentSelector: the selector expression or fragment value"
    },
    "prefix": {
      "type": "string",
      "maxLength": 500,
      "description": "TextQuoteSelector: text immediately before the selection, for disambiguation",
      "maxGraphemes": 150
    },
    "suffix": {
      "type": "string",
      "maxLength": 500,
      "description": "TextQuoteSelector: text immediately after the selection, for disambiguation",
      "maxGraphemes": 150
    },
    "conformsTo": {
      "type": "string",
      "format": "uri",
      "description": "FragmentSelector: URI of the specification the fragment conforms to"
    }
  },
  "description": "W3C Web Annotation Selector. The 'type' field discriminates the selector kind using W3C type names (e.g. TextQuoteSelector). This follows W3C conventions, not ATProto union $type."
}

target object

W3C SpecificResource - the target with optional selector

Properties

selector ref #selector Optional

W3C Selector to identify the annotated segment. Uses W3C 'type' field (not ATProto $type) per the Web Annotation Data Model.

source string uri Required

The URL being annotated

sourceHash string Optional

SHA256 hash of normalized URL for indexing

state ref #timeState Optional

State of the resource at annotation time

title string Optional

Page title at time of annotation

maxLength: 500 bytes

View raw schema

{
  "type": "object",
  "required": [
    "source"
  ],
  "properties": {
    "state": {
      "ref": "#timeState",
      "type": "ref",
      "description": "State of the resource at annotation time"
    },
    "title": {
      "type": "string",
      "maxLength": 500,
      "description": "Page title at time of annotation"
    },
    "source": {
      "type": "string",
      "format": "uri",
      "description": "The URL being annotated"
    },
    "selector": {
      "ref": "#selector",
      "type": "ref",
      "description": "W3C Selector to identify the annotated segment. Uses W3C 'type' field (not ATProto $type) per the Web Annotation Data Model."
    },
    "sourceHash": {
      "type": "string",
      "description": "SHA256 hash of normalized URL for indexing"
    }
  },
  "description": "W3C SpecificResource - the target with optional selector"
}

timeState object

W3C TimeState - record when content was captured

Properties

cached string uri Optional

URL to cached/archived version

sourceDate string datetime Optional

When the source was accessed

View raw schema

{
  "type": "object",
  "properties": {
    "cached": {
      "type": "string",
      "format": "uri",
      "description": "URL to cached/archived version"
    },
    "sourceDate": {
      "type": "string",
      "format": "datetime",
      "description": "When the source was accessed"
    }
  },
  "description": "W3C TimeState - record when content was captured"
}