id.breadcrumbs.trail Documentation (EN)

main record

One attested contribution: an author did some kind of thing to/about a subject, optionally connected to other trails or artifacts.

Record Key tid Timestamp-based ID

Properties

anchorId string Optional

Added revision 2. The stable id of a physical object (an NFC tag or printed QR on a disc/cabochon/sheet of paper) this trail is anchored to, if any -- absent for a purely digital trail (a claim, evidence, etc). The same anchorId recurs across every trail record from every person who has ever tapped that one object, forming a star topology around it; see DESIGN.md §6 / BREADCRUMBS.md.

maxLength: 512 bytes

author string did Required

The DID of whoever made the contribution this trail attests to. Usually the same DID as the record's own repo (records live in their author's PDS), but named explicitly here so a trail remains legible even when read outside that repo context, or when attesting on someone else's behalf (e.g. a labeler recording a third party's contribution).

connections array of ref #connection Optional

Typed relations from this trail to other trails or artifacts -- the same shape as an Anchor/Evidence edge or a Semble connection. Optional and open-ended on purpose: most trails (e.g. a first Claim) have none. For a physical crumb (see `anchorId`), the open relation vocabulary includes 'anchored-by' (first tap on a fresh object), 'received-from'/'handed-to' (a handoff between people) -- documented convention, not enforced by this schema.

createdAt string datetime Required

When this contribution was made.

kind string Required

What kind of contribution this is -- e.g. 'claim', 'evidence', 'question', 'project', 'review', 'attestation'. Deliberately open, not an enum: new contribution kinds shouldn't require a schema revision, matching run.saito.fact's own open-predicate design.

maxLength: 128 bytes

medium string Optional

Added revision 2. What the anchored physical object is made of -- e.g. 'sticker', 'card', 'nail', 'magnet', 'laundry', 'pendant' (the real NFC hardware in use, see photos/nfc-materials/). Only meaningful alongside anchorId; deliberately open, not an enum, so a new medium doesn't need a schema revision. Drives breadcrumbs-decay's per-medium freshness window (DESIGN.md §6).

maxLength: 64 bytes

subject string uri Required

The artifact this trail attests to or about, wherever it lives and however it's represented -- an at:// URI, an https:// URL, a doi:, an ipfs://, etc. Deliberately addressing-scheme-agnostic: breadcrumbs is the attestation layer over other systems' document shapes, not a competing one.

maxLength: 2000 bytes

View raw schema

{
  "description": "One attested contribution: an author did some kind of thing to/about a subject, optionally connected to other trails or artifacts.",
  "key": "tid",
  "record": {
    "properties": {
      "anchorId": {
        "description": "Added revision 2. The stable id of a physical object (an NFC tag or printed QR on a disc/cabochon/sheet of paper) this trail is anchored to, if any -- absent for a purely digital trail (a claim, evidence, etc). The same anchorId recurs across every trail record from every person who has ever tapped that one object, forming a star topology around it; see DESIGN.md §6 / BREADCRUMBS.md.",
        "maxLength": 512,
        "type": "string"
      },
      "author": {
        "description": "The DID of whoever made the contribution this trail attests to. Usually the same DID as the record's own repo (records live in their author's PDS), but named explicitly here so a trail remains legible even when read outside that repo context, or when attesting on someone else's behalf (e.g. a labeler recording a third party's contribution).",
        "format": "did",
        "type": "string"
      },
      "connections": {
        "description": "Typed relations from this trail to other trails or artifacts -- the same shape as an Anchor/Evidence edge or a Semble connection. Optional and open-ended on purpose: most trails (e.g. a first Claim) have none. For a physical crumb (see `anchorId`), the open relation vocabulary includes 'anchored-by' (first tap on a fresh object), 'received-from'/'handed-to' (a handoff between people) -- documented convention, not enforced by this schema.",
        "items": {
          "ref": "#connection",
          "type": "ref"
        },
        "type": "array"
      },
      "createdAt": {
        "description": "When this contribution was made.",
        "format": "datetime",
        "type": "string"
      },
      "kind": {
        "description": "What kind of contribution this is -- e.g. 'claim', 'evidence', 'question', 'project', 'review', 'attestation'. Deliberately open, not an enum: new contribution kinds shouldn't require a schema revision, matching run.saito.fact's own open-predicate design.",
        "maxLength": 128,
        "type": "string"
      },
      "medium": {
        "description": "Added revision 2. What the anchored physical object is made of -- e.g. 'sticker', 'card', 'nail', 'magnet', 'laundry', 'pendant' (the real NFC hardware in use, see photos/nfc-materials/). Only meaningful alongside anchorId; deliberately open, not an enum, so a new medium doesn't need a schema revision. Drives breadcrumbs-decay's per-medium freshness window (DESIGN.md §6).",
        "maxLength": 64,
        "type": "string"
      },
      "subject": {
        "description": "The artifact this trail attests to or about, wherever it lives and however it's represented -- an at:// URI, an https:// URL, a doi:, an ipfs://, etc. Deliberately addressing-scheme-agnostic: breadcrumbs is the attestation layer over other systems' document shapes, not a competing one.",
        "format": "uri",
        "maxLength": 2000,
        "type": "string"
      }
    },
    "required": [
      "subject",
      "author",
      "kind",
      "createdAt"
    ],
    "type": "object"
  },
  "type": "record"
}

connection object

A single typed connection from a trail to another trail or artifact.

Properties

relation string Required

The relation this connection expresses -- e.g. 'supports', 'opposes', 'explainer', 'helpful', 'addresses', per Semble's and Discourse Graphs' own vocabulary. Deliberately open, not an enum, matching `kind`.

maxLength: 128 bytes

target string uri Required

What this connection points at -- another trail's AT-URI, or any URI a subject can take (see `subject`).

maxLength: 2000 bytes

View raw schema

{
  "description": "A single typed connection from a trail to another trail or artifact.",
  "properties": {
    "relation": {
      "description": "The relation this connection expresses -- e.g. 'supports', 'opposes', 'explainer', 'helpful', 'addresses', per Semble's and Discourse Graphs' own vocabulary. Deliberately open, not an enum, matching `kind`.",
      "maxLength": 128,
      "type": "string"
    },
    "target": {
      "description": "What this connection points at -- another trail's AT-URI, or any URI a subject can take (see `subject`).",
      "format": "uri",
      "maxLength": 2000,
      "type": "string"
    }
  },
  "required": [
    "relation",
    "target"
  ],
  "type": "object"
}