# at.margin.note

> Published by [margin.at](https://lexicon.garden/identity/did:plc:rjqn3agdb74cszhqcpii4sne)

✓ This is the authoritative definition for this NSID.

## Description

W3C Web Annotation Data Model compliant unified note record for ATProto

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:rjqn3agdb74cszhqcpii4sne/at.margin.note)
- [Documentation](https://lexicon.garden/lexicon/did:plc:rjqn3agdb74cszhqcpii4sne/at.margin.note/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:rjqn3agdb74cszhqcpii4sne/at.margin.note/examples)

## Definitions

### `at.margin.note#body`

**Type**: `object`

Annotation body - the content of the annotation

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `uri` | `string` (uri) | No | Reference to external body content |
| `value` | `string` | No | Text content of the annotation. For bookmarks, this is the description. |
| `format` | `string` | No | MIME type of the body content |

### `at.margin.note`

**Type**: `record`

A W3C-compliant web annotation stored on the AT Protocol

**Key**: `tid`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `body` | `ref` → `#body` | No | The annotation content (text or reference). For bookmarks, use body.value for the description. |
| `tags` | `array` | No | Tags for categorization |
| `color` | `string` | No | Highlight color tint |
| `facets` | `array` | No | Rich text facets (e.g. mentions, links) |
| `labels` | `ref` → `com.atproto.label.defs#selfLabels` | No | Self-applied content labels for this annotation |
| `rights` | `string` (uri) | No | License URI (e.g., https://creativecommons.org/licenses/by/4.0/) |
| `target` | `ref` → `#target` | Yes | The resource being annotated with optional selector |
| `createdAt` | `string` (datetime) | Yes |  |
| `generator` | `ref` → `#generator` | No | The client/agent that created this record |
| `modifiedAt` | `string` (datetime) | No | When this record was last modified |
| `motivation` | `string` | Yes | W3C motivation for the annotation |

### `at.margin.note#target`

**Type**: `object`

W3C SpecificResource - the target with optional selector

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `state` | `ref` → `#timeState` | No | State of the resource at annotation time |
| `title` | `string` | No | Page title at time of annotation |
| `source` | `string` (uri) | Yes | The URL being annotated |
| `selector` | `ref` → `#selector` | No | W3C Selector to identify the annotated segment. Uses W3C 'type' field (not ATProto $type) per the Web Annotation Data Model. |
| `sourceHash` | `string` | No | SHA256 hash of normalized URL for indexing |

### `at.margin.note#selector`

**Type**: `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.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `end` | `integer` | No | TextPositionSelector: end character offset (exclusive) |
| `type` | `string` | Yes | W3C selector type identifier |
| `exact` | `string` | No | TextQuoteSelector: the exact text being selected |
| `start` | `integer` | No | TextPositionSelector: start character offset (inclusive) |
| `value` | `string` | No | CssSelector/XPathSelector/FragmentSelector: the selector expression or fragment value |
| `prefix` | `string` | No | TextQuoteSelector: text immediately before the selection, for disambiguation |
| `suffix` | `string` | No | TextQuoteSelector: text immediately after the selection, for disambiguation |
| `conformsTo` | `string` (uri) | No | FragmentSelector: URI of the specification the fragment conforms to |

### `at.margin.note#generator`

**Type**: `object`

The client/agent that created this record

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | `string` (uri) | No |  |
| `name` | `string` | No |  |
| `homepage` | `string` (uri) | No |  |

### `at.margin.note#timeState`

**Type**: `object`

W3C TimeState - record when content was captured

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `cached` | `string` (uri) | No | URL to cached/archived version |
| `sourceDate` | `string` (datetime) | No | When the source was accessed |

## Raw Schema

```json
{
  "id": "at.margin.note",
  "defs": {
    "body": {
      "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"
    },
    "main": {
      "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"
    },
    "target": {
      "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"
    },
    "selector": {
      "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."
    },
    "generator": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        },
        "name": {
          "type": "string"
        },
        "homepage": {
          "type": "string",
          "format": "uri"
        }
      },
      "description": "The client/agent that created this record"
    },
    "timeState": {
      "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"
    }
  },
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1,
  "revision": 3,
  "description": "W3C Web Annotation Data Model compliant unified note record for ATProto"
}
```