Records¶

Bases: Model

An alignment between two parallel sequences. The sequences can be tokenizations, annotation layers, expressions (for parallel text), or tiers. Links establish many-to-many correspondence between elements indexed by position.

Bases: Model

A role/argument reference in a predicate-argument structure. Uses the composable objectRef to point to another annotation, either locally (same layer, by UUID) or remotely (cross-layer or cross-record, by AT-URI + UUID).

Bases: Model

A single abstract annotation. The fields populated depend on the layer's kind/subkind. For token-tags: tokenIndex + label. For spans: anchor + label. For trees: anchor + label + parentId/childIds. For relations: anchor + arguments. For graphs: anchor + arguments or headIndex/targetIndex. This single type replaces the former tag, spanAnnotation, entityMention, situationMention, dependencyArc, parseNode, etc.

Bases: Model

A named layer of annotations over an expression. All annotation types use this single record type. The combination of kind, subkind, and formalism tells the appview how to render. Multiple layers can coexist for the same expression.

Bases: Model

A cluster of annotations (e.g., coreferent entity mentions, situation mentions referring to the same situation).

Bases: Model

Groups annotations into equivalence classes. Used for coreference resolution (entity clusters, situation clusters), bridging anaphora grouping, and any annotation clustering task.

Bases: Model

An individual change entry. The targets field uses objectRef for machine-readable sub-record targeting, allowing a change item to point at specific objects within the subject record.

Bases: Model

A group of changes under a single category.

Bases: Model

A semantic version following the major.minor.patch convention.

Bases: Model

A changelog entry describing changes to any Layers record.

Bases: Model

How disagreements between annotators are resolved into a final annotation.

Bases: Model

An acceptance criterion for annotation quality.

Bases: Model

How many annotators work on each item and how they are assigned.

Bases: Model

Annotation project design parameters: annotator assignment, adjudication, and quality criteria.

Bases: Model

A corpus: a curated collection of expressions.

Bases: Model

A record indicating that a expression belongs to a corpus, with optional split assignment.

Bases: Model

A reference to an external knowledge base entry. Supports ATProto-native KBs (e.g., chive.pub with AT-URI nodes), external KBs (e.g., Wikidata with QIDs), and user/persona-specific KBs (AT-URIs in user PDSes).

Bases: Model

How the referenced bytes may actually be obtained. 0.8.0 carries licensing but no gate: it can say a corpus is LDC-User-Agreement licensed but not that obtaining it requires a signed agreement with a named body. Layers DECLARES access conditions and cannot ENFORCE them, because every record it indexes lives in someone else's PDS; the block exists so a consumer knows where the gate is before wasting a request.

Bases: Model

A composable reference to any agent (human annotator, ML model, crowd worker, expert panel, etc.) that produced data. Separates the identity of the producer from the interpretive framework (persona) and the software used (tool). Consumers dispatch on which field(s) are populated: did for ATProto-native agents, id for anonymized or platform-specific identifiers, knowledgeRef for externally grounded agents (ORCID, HuggingFace model card, Wikidata).

Bases: Model

A single key-value feature.

Bases: Model

An open-ended set of typed key-value features that can be attached to any annotation. Provides maximum extensibility without committing to any label set or linguistic theory.

Bases: Model

A single link in an alignment between two parallel sequences. Maps element(s) in a source sequence to element(s) in a target sequence. Supports many-to-many correspondence for interlinear glossing, parallel text alignment, cross-tokenization mapping, etc.

Bases: Model

A universally unique identifier for cross-referencing annotation objects.

Bases: Model

A composable reference to any Layers object, whether local (same record, by UUID), remote (different record, by AT-URI + optional object UUID), or external (knowledge graph entry). This is the universal cross-referencing primitive; consumers dispatch on which field(s) are populated. Used by argumentRef, graphNode, alignment endpoints, and any other cross-object pointer.

Bases: Model

Identifies which medium, session clock, stream, and track a sample-indexed or time-indexed anchor is measured against. Absent means the single medium reachable from the annotated expression, which preserves the single-stream reading of records that omit it.

Bases: Model

A spatial bounding box for image or video frame annotation.

Bases: Model

W3C FragmentSelector: selects by URI fragment identifier.

Bases: Model

W3C TextPositionSelector adapted for ATProto: selects by UTF-8 byte offsets. Semantically equivalent to pub.layers.defs#span but named for W3C compatibility with at.margin.

Bases: Model

W3C TextQuoteSelector: selects text by quoting it with surrounding context. Compatible with at.margin.annotation and the W3C Web Annotation Data Model.

Bases: TaggedUnion

W3C selector for identifying the specific segment within the resource.

Bases: ExternalTargetSelector

The 'textQuoteSelector' member of ExternalTargetSelector.

Bases: ExternalTargetSelector

The 'textPositionSelector' member of ExternalTargetSelector.

Bases: ExternalTargetSelector

The 'fragmentSelector' member of ExternalTargetSelector.

Bases: Model

Target for annotating external resources (web pages, documents, etc.). Compatible with at.margin's target model and the W3C Web Annotation Data Model.

Bases: Model

A contiguous span of text defined by UTF-8 byte offsets.

Bases: Model

Anchor to a specific page and region in a paged document (PDF, etc.). Compatible with chive.pub's page-level annotation model.

Bases: Model

A frequency band selecting a sub-band of a continuous signal (e.g., an EEG rhythm or a speech formant). Follows the URI+slug pattern; explicit low/high bounds override the slug where present.

Bases: Model

A normalized spatial value representing a point, region, line, or complex geometry. Parallel to temporalEntity. Subsumes GeoJSON geometry types, WKT primitives, and ISO 19107 spatial schema. Consumers dispatch on which fields are populated: bbox only (pixel bounding box), geometry+type (parsed geometry string), geometry+geometryFormat (format-specific parsing).

Bases: Model

A span over one or more channels of a continuous signal (EEG, MEG, ECoG, audio waveform, motion or eye-tracking stream). Addressable by sample index or by session-relative nanoseconds; scope is required because an unscoped sample index is meaningless.

Bases: Model

A spatial annotation at a specific time point.

Bases: Model

A temporal span within a media source, defined by start and end times in milliseconds on the referenced session or stream clock. Times are signed and session-relative (they may precede the clock origin, matching BIDS StartTime); they are never UTC-epoch values.

Bases: Model

Combined spatial and temporal anchor for video annotation with keyframe-based tracking.

Bases: Model

A reference to a specific token within a tokenization, by index.

Bases: Model

A sequence of token references, possibly non-contiguous, within a single tokenization.

Bases: Model

Abstract anchor: how an annotation attaches to its source data. This is a polymorphic type; at least one anchoring field should be present. Consumers dispatch on which field(s) are populated.

Bases: Model

A structured content hash for integrity verification. Separates the algorithm from the digest value so verifiers dispatch on algorithm rather than parsing a packed string.

Bases: Model

Metadata about who or what produced an annotation, when, and with what confidence. The three key provenance fields are: agent (who did it), personaRef (under what framework), and tool (with what software).

Bases: Model

An abstract constraint expression. Used for type constraints on role slots, slot-level constraints in templates, cross-slot agreement constraints, and any other declarative restriction. The expression field holds a DSL string whose format is identified by expressionFormat/expressionFormatUri.

Bases: Model

A reference to an ethics or institutional review board approval covering a piece of work. Shared across acquisition consent, sessions, and reproducibility info.

Bases: Model

A reference to a grant or award that funded a piece of work. Shared across acquisition consent and reproducibility info.

Bases: Model

Information about how to reproduce a dataset or the data produced from an eprint. Shared by data-producing produces (corpus, annotation layers, experiments) and eprint data links.

Bases: Model

An instrument used in acquisition. Manufacturer, product and software are GROUNDED through defs#knowledgeRef rather than enumerated: an organization is a citable entity reachable via ror and wikidata, a package via rrid, and enumerating vendors in a released lexicon makes a rebrand a lexicon version bump. BIDS Manufacturer, ManufacturersModelName, DeviceSerialNumber, SoftwareVersions, SoftwareRRID; NWB Device.

Bases: Model

A structured reference to a language or language variety, decomposing a BCP-47 tag into its codes plus a knowledge-graph grounding and a role. The tag is the canonical addressable key; importers normalize it on write.

Bases: Model

Detail for a single license. Follows the URI+slug pattern (spdxUri is the canonical knowledge-graph node, spdx is the human-readable fallback) and mirrors one entry of a DataCite rightsList (rightsIdentifier + rightsURI).

Bases: Model

Complete licensing terms for a released artifact. Represents single, dual/multi (choose-one), composite (all-apply), exception (WITH), and component-scoped licensing. The SPDX license expression encodes the boolean relationship between licenses; the licenses array carries per-license detail.

Bases: Model

Qualitative modification of a spatial value. Parallel to temporalModifier. Indicates precision, derivation method, or processing applied to a spatial entity.

Bases: Model

A complete spatial annotation packaging the expression type, normalized value, modifier, anchoring, and document function. Parallel to temporalExpression. Subsumes ISO-Space place annotations (ISO 24617-7), SpatialML PLACE elements, and general spatial semantic annotation. Attach to annotation objects via the spatial field.

Bases: Model

A normalized temporal value representing a point, interval, duration, or uncertain range in calendar/clock time. Subsumes OWL-Time TemporalEntity (Instant, Interval, Duration) and TimeML TIMEX3 value. Consumers dispatch on which fields are populated: instant only (point), intervalStart+intervalEnd (bounded interval), duration only (pure duration), earliest+latest (uncertain bounds), recurrence (repeating pattern).

Bases: Model

Qualitative modification of a temporal value. Subsumes TimeML TIMEX3 mod attribute and OWL-Time DateTimeDescription qualifiers.

Bases: Model

A complete temporal annotation packaging the expression type, normalized value, modifier, anchoring, and document function. Subsumes TimeML TIMEX3 and OWL-Time GeneralDateTimeDescription. Attach to annotation objects via the temporal field.

Bases: Model

A bibliographic creator (author, editor, etc.). Name parts follow CSL-JSON; nameType and affiliation follow DataCite. ATProto-native creators additionally ground identity via agent (DID) or knowledgeRef (ORCID, ROR, OpenAlex).

Bases: Model

A date in CSL-JSON style: structured year/month/day and/or a free-form literal. Maps to CSL 'date-parts' (when year/month/day are set) or 'literal'/'raw' (when only literal is set).

Bases: Model

A bibliographic citation, expressible as a raw formatted string (raw) and/or structured fields following CSL-JSON and DataCite conventions. Consumers prefer the structured fields when present and fall back to raw. Populate at least raw or title.

Bases: Model

A link from an eprint to the Layers data it produced or is associated with. Generalizes the former chive-specific eprintDataLink.

Bases: Model

A link between a Layers data record and an eprint.

Bases: Model

An expression record representing a linguistic data source or unit at any granularity, from full documents down to individual morphemes.

Bases: Model

A single directed typed edge between any two Layers objects. Supports multidigraphs and cycles. Source and target use objectRef, which can point to local UUIDs, remote AT-URIs, or external knowledge graph nodes.

Bases: Model

A single directed edge entry within a graphEdgeSet.

Bases: Model

A batch of typed, directed edges between Layers objects. Use for bulk edge creation when many edges share the same provenance and context.

Bases: Model

A standalone node in the property graph. Represents entities, concepts, situations, claims, or any domain object that does not have another Layers record. Existing Layers records (expressions, annotations, typeDefs) are implicitly nodes via objectRef.

Bases: Model

An inter-annotator agreement report summarizing agreement metrics across judgment sets.

Bases: Model

A constraint on item list construction for an experiment.

Bases: Model

Experiment design parameters for item distribution, ordering, and timing.

Bases: Model

How stimuli are displayed to participants.

Bases: Model

A data capture instrument used in an experiment.

Bases: Model

Definition of an annotation or judgment experiment.

Bases: Model

A single judgment about a linguistic item.

Bases: Model

A set of judgments from a single annotator for an experiment.

Bases: Model

A per-region reading-time or response measurement within a judgment, addressing one region of the presented stimulus (e.g., in self-paced reading or eye-tracking region analysis).

Bases: Model

Composable audio metadata. Attach to any media record representing audio content: standalone audio files, audio tracks in video, etc.

Bases: Model

A named point in the enclosing coordinate system, in that system's unit.

Bases: Model

The frame in which sensor, landmark, or volume coordinates are expressed. BIDS coordsystem.json, which requires a named system plus units and RECOMMENDS FiducialsCoordinates and AnatomicalLandmarkCoordinates. One def for all four use sites, so the four divergent lists the proposals carried collapse to one.

Bases: Model

Composable document/image metadata. Attach to any media record representing scanned documents, manuscripts, printed text, or other page-based media for OCR/HTR annotation workflows.

Bases: Model

One trigger code and what it means. Grounds BIDS events.tsv trial_type, a bare string upstream, in a type definition node.

Bases: Model

Composable eye-tracking metadata, carried alongside signalInfo. Screen geometry is deliberately absent: the same tracker at a different viewing distance yields different degrees of visual angle, so it is a property of stimulus presentation and lives on pub.layers.judgment.defs#presentationSpec.screen, which is where BIDS puts it (the StimulusPresentation object of the events sidecar).

Bases: Model

One filter applied to a recording. BIDS makes SoftwareFilters REQUIRED and HardwareFilters RECOMMENDED and types both as arbitrary nested JSON, so a consumer cannot today decide whether a recording is admissible for a given analysis without reading prose. Every parameter here is an integer in a named unit.

Bases: Model

Composable still-image metadata. Added because 0.8.0 has no image block at all, so a photograph's width and height had to borrow videoInfo, whose own description says it is for video content.

Bases: Model

Composable motion-capture and articulography metadata: optical marker systems, inertial suits, electromagnetic articulography, ultrasound tongue imaging, and body or hand pose streams. Follows BIDS Motion, in which a tracking system is a grouping level below the session, so one session routinely carries several media records at different rates. A motion stream also carries signalInfo, because in BIDS Motion a mocap channel is typed POS, ORNT, VEL, ACCEL, GYRO, MAGN, ANGACCEL or JNTANG, that is, it is a sampled signal.

Bases: Model

Physical placement of one sensor: an EEG electrode, an iEEG contact, a MEG coil, an fNIRS optode, a motion marker, or an anatomical landmark. Coordinates are signed integer nanometres in the frame named by the enclosing coordinateSystem.

Bases: Model

One recorded channel. BIDS channels.tsv, whose name, type and units columns are REQUIRED for every electrophysiology modality and which additionally makes low_cutoff and high_cutoff REQUIRED for iEEG. Position is held by reference through sensor, because channel and sensor are not in one-to-one correspondence.

Bases: Model

Composable metadata for a sampled time-series recording. Attach to any media record of kind signal or motion. Frequencies are millihertz because BIDS types SamplingFrequency as number and 512.03 Hz occurs; lengths are nanometres because iEEG contact localization is reported sub-millimetre; times are session-relative nanoseconds, never UTC-epoch, since 2^53 ns is about 104 days.

Bases: Model

How one media stream aligns to a session's shared time base. This is what makes multimodal Layers possible: the 0.8.0 chain is annotationLayer.expression (single, REQUIRED) to expression.mediaRef (single), so a session of two cameras, a lapel microphone, an EEG cap and an eye tracker is unrepresentable, and parentMediaRef with startOffsetMs expresses excerpt-of, a different relation.

Bases: Model

Composable video metadata. Attach to any media record representing video content.

Bases: Model

Composable metadata for volumetric imaging: fMRI runs, structural scans, and derived masks or parcellations. Volumes almost always exceed the blob cap, so externalUri plus contentDigest is the normal carriage rather than the exception.

Bases: Model

A media source record (audio, video, image, document, signal, motion, or volume) that can be referenced by expressions and annotations. Modality-specific metadata lives in composable info objects; a single medium may carry several (a motion stream also carries signalInfo).

Bases: Model

An annotation ontology: a collection of typed definitions (entity types, situation types, role types, relation types) that together form a complete annotation framework.

Bases: Model

A role/argument slot in a frame or situation type definition. Structurally parallel to pub.layers.resource#slot: both represent named positions with type constraints. roleSlot is ontology-level (what roles a frame type allows); resource slot is template-level (what variables a template exposes).

Bases: Model

A type definition within an ontology. Covers entity types, situation types, role types, and relation types in a single unified model.

Bases: Model

A persona representing an annotator's role, expertise, and interpretive framework.

Bases: Model

A named collection of linguistic resource entries. Abstract enough to represent bead Lexicons, FrameNet frame inventories, PropBank frame files, WordNet synsets, morphological paradigm tables, gazetteers, stop-word lists, etc.

Bases: Model

Links an entry to a collection. Separate record enables many-to-many relationships (an entry can belong to multiple collections) and decentralized curation (anyone can propose membership).

Bases: Model

A component of a multi-word expression entry.

Bases: Model

A linguistic resource entry: a lexical item, frame element filler, morphological paradigm cell, or any atomic unit in a structured linguistic collection. Abstract enough to represent bead LexicalItems, FrameNet lexical units, PropBank rolesets, WordNet synset members, morphological paradigm cells, etc.

Bases: Model

A single slot→filler mapping in a filled template. The filler can be an entry reference (AT-URI to a resource entry), a literal value, or both (entry reference with rendered surface form).

Bases: Model

A filled template: a template with all slots mapped to specific fillers, producing a rendered text. Generalizes bead's FilledTemplate and Item. The rendered text can optionally be materialized as a pub.layers.expression for annotation. Fillings are composable: they reference templates, entries, and communications via AT-URIs.

Bases: Model

A named variable slot in a template. Generalizes bead's Slot (template variable position with constraints and defaults), ontology roleSlots (argument positions with filler type constraints), and similar parameterized positions in any structured linguistic pattern. Slots are composable: they can reference collections of allowed fillers, ontology types, or express arbitrary constraints.

Bases: Model

A parameterized text template with named variable slots. Generalizes bead's Template (text pattern with {slotName} placeholders, slot definitions, and cross-slot constraints) and similar pattern structures used for stimulus generation, item construction, data augmentation, and controlled natural language. Templates are composable: they can reference ontologies, collections, and other templates.

Bases: Model

A member in a template composition. References either a template or a nested composition.

Bases: Model

A composition of templates (sequence, tree, or other structure). Used for multi-part stimuli, template hierarchies, and complex item construction.

Bases: Model

A single token within a tokenization.

Bases: Model

An ordered sequence of tokens for an expression or sub-expression. Multiple tokenizations can coexist for the same expression (e.g., whitespace vs. BPE vs. morphological), enabling interlinear glossing, alternative segmentation strategies, or multi-granularity analysis.

Bases: Model

A segmentation of an expression into tokenizations. Structural hierarchy (sections, sentences, paragraphs) is expressed via expression records with parentRef; this record provides the token-level decomposition.