Context layer

The context layer

A schema defines the shape of your data. The context layer is the typed meaning attached to that shape — what a field means, which source to trust, how long to keep it. People, tools, and agents read and write it as annotations.

How it works

Annotation types and annotations

Annotations are the data of the context layer. Each annotation is created against an annotation type, and its content is validated against that type's schema when it is saved — so the meaning stays structured and queryable, not prose in a README.

Annotation type — a name + a schema

{
  "id": "quality-labs/annotation-types/freshness-policy",
  "schema": {
    "required": ["staleAfterDays", "onStale"],
    "properties": {
      "staleAfterDays": { "type": "integer" },
      "onStale": { "enum": ["warn", "refetch", "reject"] }
    }
  }
}

defines what an annotation may contain

Annotation — an instance attached to a subject

{
  "type": "quality-labs/annotation-types/freshness-policy",
  "subject": "acme/schemas/customer",
  "author": "billing",
  "content": { "staleAfterDays": 30, "onStale": "refetch" }
}

content validated against the type's schema

An annotation type is more than a validated shape. It pairs a name with a schema — the schema checks each annotation's content, and the type is not itself a schema — and it sets how annotations of that type are applied: whether their content stays editable or is locked once written, and whether an account can annotate a given subject once or many times. Defining a type is where you make those calls.

Rusl's API, routes, and CLI all say annotation type; conceptually it is a context type — the value name for the same unit.

An annotation always attaches to a subject — a schema, a version, a bundle, even another annotation — identified by its GUID. The subject's kind is derived, so you never set it by hand.

Defining a type

What you choose when you define a type

An annotation type fixes a few decisions up front. Most lock after creation — only the description, the active-annotation limit (which can be relaxed, never tightened), and discovery details stay editable.

Validator schema: The schema each annotation's content is checked against.
Validation mode: Track the schema's latest version, or pin one version.
Active annotation limit: One annotation per subject per account, or many.
Immutability: Whether an annotation's content can be edited after it is created.
Visibility: Public, or private to your account.

Self-describing

Types can describe other types

The schema that backs an annotation type is itself a subject — so a type can be annotated by other types. There is no privileged meta-level: the meaning describes the things that hold meaning.

Rusl's own seed data does this. The schema behind the context-request type carries a semantic-link annotation pointing at usage-report — one context type declaring how it relates to another.

A semantic-link annotation on the context-request type's schema

{
  "type": "rusl/annotation-types/semantic-link",
  "subject": "rusl/schemas/context-request",
  "content": {
    "target_uri": "rusl/usage-report",
    "relationship_type": "provides_context_for",
    "relation_weight": 8
  }
}

from Rusl's seed data

The feedback bundle

A starter set of context types

Rusl ships a small, growing set of standard context types as a bundle — rusl/bundles/feedback-schemas. Install it like any other bundle to start attaching real context before you define your own types.

The bundle's manifest is the source of truth for what it contains. Today that includes types such as usage-report, domain-interpretation, semantic-link, and trust-signal.

Browse the feedback bundle

Create your first

Walk through authoring a type and attaching an annotation.

Create your first annotation type