at.margin.annotation

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)

createdAt string datetime Required

An RFC 3339 formatted timestamp.

generator ref #generator Optional

The client/agent that created this record

motivation string Optional

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": [
      "target",
      "createdAt"
    ],
    "properties": {
      "body": {
        "ref": "#body",
        "type": "ref",
        "description": "The annotation content (text or reference)"
      },
      "tags": {
        "type": "array",
        "items": {
          "type": "string",
          "maxLength": 64,
          "maxGraphemes": 32
        },
        "maxLength": 10,
        "description": "Tags for categorization"
      },
      "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"
      },
      "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

language string Optional

BCP47 language tag

uri string uri Optional

Reference to external body content

value string Optional

Text content of the annotation

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",
      "maxGraphemes": 3000
    },
    "format": {
      "type": "string",
      "default": "text/plain",
      "description": "MIME type of the body content"
    },
    "language": {
      "type": "string",
      "description": "BCP47 language tag"
    }
  },
  "description": "Annotation body - the content of the annotation"
}
cssSelector object

W3C CssSelector - select DOM elements by CSS selector

Properties

type string Optional

No description available.

value string Required

CSS selector string

maxLength: 2000 bytes
View raw schema 
{
  "type": "object",
  "required": [
    "value"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "CssSelector"
    },
    "value": {
      "type": "string",
      "maxLength": 2000,
      "description": "CSS selector string"
    }
  },
  "description": "W3C CssSelector - select DOM elements by CSS selector"
}
fragmentSelector object

W3C FragmentSelector - select by URI fragment

Properties

conformsTo string uri Optional

Specification the fragment conforms to

type string Optional

No description available.

value string Required

Fragment identifier value

maxLength: 1000 bytes
View raw schema 
{
  "type": "object",
  "required": [
    "value"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "FragmentSelector"
    },
    "value": {
      "type": "string",
      "maxLength": 1000,
      "description": "Fragment identifier value"
    },
    "conformsTo": {
      "type": "string",
      "format": "uri",
      "description": "Specification the fragment conforms to"
    }
  },
  "description": "W3C FragmentSelector - select by URI fragment"
}
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"
}
rangeSelector object

W3C RangeSelector - select range between two selectors

Properties

type string Optional

No description available.

View raw schema 
{
  "type": "object",
  "required": [
    "startSelector",
    "endSelector"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "RangeSelector"
    },
    "endSelector": {
      "refs": [
        "#textQuoteSelector",
        "#textPositionSelector",
        "#cssSelector",
        "#xpathSelector"
      ],
      "type": "union",
      "description": "Selector for range end"
    },
    "startSelector": {
      "refs": [
        "#textQuoteSelector",
        "#textPositionSelector",
        "#cssSelector",
        "#xpathSelector"
      ],
      "type": "union",
      "description": "Selector for range start"
    }
  },
  "description": "W3C RangeSelector - select range between two selectors"
}
target object

W3C SpecificResource - the target with optional selector

Properties

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": {
      "refs": [
        "#textQuoteSelector",
        "#textPositionSelector",
        "#cssSelector",
        "#xpathSelector",
        "#fragmentSelector",
        "#rangeSelector"
      ],
      "type": "union",
      "description": "Selector to identify the specific segment"
    },
    "sourceHash": {
      "type": "string",
      "description": "SHA256 hash of normalized URL for indexing"
    }
  },
  "description": "W3C SpecificResource - the target with optional selector"
}
textPositionSelector object

W3C TextPositionSelector - select by character offsets

Properties

end integer Required

Ending character position (exclusive)

minimum: 0
start integer Required

Starting character position (0-indexed, inclusive)

minimum: 0
type string Optional

No description available.

View raw schema 
{
  "type": "object",
  "required": [
    "start",
    "end"
  ],
  "properties": {
    "end": {
      "type": "integer",
      "minimum": 0,
      "description": "Ending character position (exclusive)"
    },
    "type": {
      "type": "string",
      "const": "TextPositionSelector"
    },
    "start": {
      "type": "integer",
      "minimum": 0,
      "description": "Starting character position (0-indexed, inclusive)"
    }
  },
  "description": "W3C TextPositionSelector - select by character offsets"
}
textQuoteSelector object

W3C TextQuoteSelector - select text by quoting it with context

Properties

exact string Required

The exact text to match

maxLength: 5000 bytesmaxGraphemes: 1500 graphemes
prefix string Optional

Text immediately before the selection

maxLength: 500 bytesmaxGraphemes: 150 graphemes
suffix string Optional

Text immediately after the selection

maxLength: 500 bytesmaxGraphemes: 150 graphemes
type string Optional

No description available.

View raw schema 
{
  "type": "object",
  "required": [
    "exact"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "TextQuoteSelector"
    },
    "exact": {
      "type": "string",
      "maxLength": 5000,
      "description": "The exact text to match",
      "maxGraphemes": 1500
    },
    "prefix": {
      "type": "string",
      "maxLength": 500,
      "description": "Text immediately before the selection",
      "maxGraphemes": 150
    },
    "suffix": {
      "type": "string",
      "maxLength": 500,
      "description": "Text immediately after the selection",
      "maxGraphemes": 150
    }
  },
  "description": "W3C TextQuoteSelector - select text by quoting it with context"
}
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"
}
xpathSelector object

W3C XPathSelector - select by XPath expression

Properties

type string Optional

No description available.

value string Required

XPath expression

maxLength: 2000 bytes
View raw schema 
{
  "type": "object",
  "required": [
    "value"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "XPathSelector"
    },
    "value": {
      "type": "string",
      "maxLength": 2000,
      "description": "XPath expression"
    }
  },
  "description": "W3C XPathSelector - select by XPath expression"
}

Lexicon Garden

@