Layers

Composable linguistic annotation lexicons for ATProto

Documentation · Discussions · Bluesky

What is Layers?

Layers defines AT Protocol Lexicon schemas under pub.layers.* for publishing linguistic annotations. Its records cover text, audio, video, images, experimental judgments, physiological signals, and the metadata needed to connect those materials.

The schemas provide a common target for formats such as CoNLL-U, brat, ELAN, TEI, WebVTT, Universal Dependencies, AMR, and semantic-role resources. Records remain in user-controlled Personal Data Servers (PDSes), where other ATProto services can resolve and compose them.

This repository contains the lexicon schemas and their documentation. Appview implementations, generated language bindings, and application code are versioned separately from this schema release.

Version 0.9.0

Version 0.9.0 contains 114 pub.layers.* lexicon files:

• 30 record collections
• 65 query or procedure methods
• shared definition lexicons
• six OAuth permission-set lexicons

The release adds two record families. pub.layers.acquisition.* represents participants and synchronized data-collection sessions. pub.layers.catalog.* provides citable collections and typed membership across corpora, resources, experiments, media, and other Layers records.

Version 0.9.0 also expands the anchor model for images, video, continuous signals, and synchronized sessions; adds BIDS- and NWB-oriented media and acquisition metadata; changes record keys from tid to any; and replaces the packed annotation digest string with a structured contentDigest object. See the changelog for the compatibility notes.

Data model

The central dependency chain is:

Expression -> Segmentation -> Annotation

Expressions identify linguistic material. Segmentations identify units within that material. Annotation layers assign typed values to anchored spans or units. Other record families add reusable ontologies, corpora, resources, judgments, alignments, graphs, personas, media, scholarly provenance, acquisition sessions, catalogs, and change histories.

Schema group	Purpose
pub.layers.defs	Shared references, anchors, selectors, metadata, and provenance
pub.layers.expression	Recursive documents and linguistic expressions
pub.layers.segmentation	Tokenization strategies and token sequences
pub.layers.annotation	Annotation layers and cluster sets
pub.layers.ontology	Type systems, roles, and theoretical frameworks
pub.layers.corpus	Corpora and corpus membership
pub.layers.resource	Lexical entries, templates, fillings, and collections
pub.layers.judgment	Experiments, judgment sets, and agreement reports
pub.layers.alignment	Cross-lingual and cross-modal correspondences
pub.layers.graph	Typed graph nodes, edges, and edge sets
pub.layers.persona	Annotator personas and annotation frameworks
pub.layers.media	Audio, video, image, and signal metadata
pub.layers.eprint	Scholarly metadata and data provenance links
pub.layers.acquisition	Participants and data-collection sessions
pub.layers.catalog	Collections and memberships across record families
pub.layers.changelog	Structured changes with sub-record targeting
pub.layers.integration	Foreign-record lookup and panproto lens application
pub.layers.auth*	OAuth permission sets for appview operations

See the documentation for field references, design guidance, and data-model mappings.

Repository structure

layers/
├── lexicons/
│   ├── pub/layers/       # Released pub.layers.* schemas
│   ├── foreign/          # Vendored source schemas used by cross-app lenses
│   ├── lenses/           # Panproto mappings from foreign records to Layers
│   └── upstream/         # Typed source-format theories and projections
├── docs/                 # Docusaurus documentation site
├── CHANGELOG.md          # Schema release history and compatibility notes
└── validate-lexicons.mjs # Lexicon and cross-reference validator

The JSON files in lexicons/pub/layers/ are the source of truth for the released schema. Supporting foreign schemas and mappings do not change the meaning of the pub.layers.* records.

Validate

Run the schema validator from the repository root:

npm ci
npm test

Build the documentation separately:

npm --prefix docs ci
npm --prefix docs run build

The validator parses every pub.layers.* lexicon, registers the complete family, and checks that all references resolve.

Contributing

Open an issue for a concrete defect or proposal. Use discussions for schema design and interoperability questions.

License

Licensed under CC-BY-SA-4.0.