Add Vocab

Do not rely solely on automated checks (mise run check)—they verify only TypeScript compilation, not semantic correctness of the vocabulary.

Workflow

1. Read the spec document (FEP, W3C spec, or informal documentation) carefully
2. Identify the type's URI, JSON-LD context, and properties
3. Check whether the JSON-LD context URL is already preloaded in packages/vocab-runtime/src/contexts.ts
4. Create the YAML file at packages/vocab/src/<typename-lowercase>.yaml
5. If a new context URL is needed, add it to packages/vocab-runtime/src/contexts.ts
6. Run mise run codegen to generate TypeScript classes
7. Run mise run check to verify everything compiles
8. Ask the user to review the YAML definition and generated code carefully before committing

The generated TypeScript class is automatically exported from @fedify/vocab via packages/vocab/src/vocab.ts (generated) and packages/vocab/src/mod.ts.

YAML file format

Every YAML file must begin with the schema reference:

$schema: ../../vocab-tools/schema.yaml

Top-level fields

Entity vs. value type (entity flag):

• entity: true — property accessors are async and can fetch remote objects
• entity: false — property accessors are synchronous; used for embedded value objects (e.g. Endpoints, Source, Hashtag)

defaultContext format

The defaultContext field specifies the JSON-LD @context written when toJsonLd() is called. It can be:

A single context URL:

defaultContext: "https://www.w3.org/ns/activitystreams"

An array of URLs and/or embedded context objects:

defaultContext:
  - "https://www.w3.org/ns/activitystreams"
  - "https://w3id.org/security/data-integrity/v1"
  - toot: "http://joinmastodon.org/ns#"
    Emoji: "toot:Emoji"
    sensitive: "as:sensitive"
    featured:
      "@id": "toot:featured"
      "@type": "@id"

Embedded context entries are YAML mappings where:

• String value "prefix:term" or "https://..." defines a simple term alias
• Object value with "@id" and optionally "@type": "@id" defines a term that should be treated as an IRI (linked resource)

Ensuring complete compaction coverage

The defaultContext must cover every term that appears in the JSON-LD document produced by toJsonLd(), including:

1. The type's own compactName — if the type has a compactName, the context must map that name to the type's URI.

2. All own property compactNames — every property defined directly on this type must have its compactName (or full URI fallback) resolvable via the context.

3. Inherited properties — properties from parent types are usually covered by the parent's context URL (e.g., https://www.w3.org/ns/activitystreams covers all core ActivityStreams properties). Verify that the parent's context URL is included.

4. Properties of embedded types — when a property's value is an object type that is serialized inline (not just referenced by URL), the context must also cover all of that embedded type's properties. This is the most commonly missed case.

   Common embedded types and the context URLs that cover them:

   Embedded type	Context URL to include
   DataIntegrityProof (from proof)	https://w3id.org/security/data-integrity/v1
   Key (from publicKey)	https://w3id.org/security/v1
   Multikey (from assertionMethod)	https://w3id.org/security/multikey/v1
   DidService (from service)	https://www.w3.org/ns/did/v1
   PropertyValue (from attachment)	schema.org terms in embedded context

5. Redundant property compactNames — if a property has redundantProperties, all their compactNames must also be defined in the context.

Practical rule: look at an existing type with similar embedded relationships as a reference. For example, Note and Article include "https://w3id.org/security/data-integrity/v1" because they embed DataIntegrityProof objects via the proof property. Person additionally includes security and DID contexts because it embeds Key, Multikey, and DidService objects inline.

Omitting a required context causes silent compaction failure: the property appears in expanded form ("https://example.com/ns#term": [...]) rather than compact form ("term": ...) in the output.

Property definitions

Each entry in properties is one of two kinds:

Non-functional property (multiple values)

Generates get<PluralName>() async iterable and optionally a singular accessor.

- pluralName: attachments # accessor: getAttachments() / attachments
  singularName: attachment # used if singularAccessor: true
  singularAccessor: true # also generate getAttachment() / attachment
  compactName: attachment # JSON-LD compact key
  uri: "https://www.w3.org/ns/activitystreams#attachment"
  description: |
    Identifies a resource attached or related to an object.
  range:
    - "https://www.w3.org/ns/activitystreams#Object"
    - "https://www.w3.org/ns/activitystreams#Link"

Required: pluralName, singularName, uri, description, range

Optional: singularAccessor (default false), compactName, subpropertyOf, container ("graph" or "list"), embedContext, untyped

Functional property (exactly one value)

Generates a single get<SingularName>() / <singularName> accessor.

- singularName: published
  functional: true
  compactName: published
  uri: "https://www.w3.org/ns/activitystreams#published"
  description: The date and time at which the object was published.
  range:
    - "http://www.w3.org/2001/XMLSchema#dateTime"

Required: singularName, functional: true, uri, description, range

Optional: compactName, subpropertyOf, redundantProperties, untyped, embedContext

Redundant properties (functional only)

When a property has equivalent URIs from multiple vocabularies, use redundantProperties to write all aliases on serialization and try them in order on deserialization:

- singularName: quoteUrl
  functional: true
  compactName: quoteUrl
  uri: "https://www.w3.org/ns/activitystreams#quoteUrl"
  redundantProperties:
    - compactName: _misskey_quote
      uri: "https://misskey-hub.net/ns#_misskey_quote"
    - compactName: quoteUri
      uri: "http://fedibird.com/ns#quoteUri"
  description: The URI of the quoted ActivityStreams object.
  range:
    - "fedify:url"

The embedContext field

Use embedContext when a nested object should carry its own @context (e.g., proof graphs in Data Integrity):

embedContext:
  compactName: proof # key under which the context is embedded
  inherit: true # use the same context as the enclosing document

The untyped field

When untyped: true, the serialized value will not have a @type field. Requires exactly one type in range. Used for embedded anonymous structures:

- singularName: source
  functional: true
  compactName: source
  uri: "https://www.w3.org/ns/activitystreams#source"
  description: The source from which the content markup was derived.
  untyped: true
  range:
    - "https://www.w3.org/ns/activitystreams#Source"

Range type reference

XSD scalar types → TypeScript types

Security scalar types

Fedify internal types

Vocabulary types

Any uri from another YAML vocabulary file can be used as a range. The TypeScript type will be the corresponding generated class (e.g., "https://www.w3.org/ns/activitystreams#Object" → Object).

Adding preloaded JSON-LD contexts

When defaultContext references a URL not already in packages/vocab-runtime/src/contexts.ts, add it to preloadedContexts.

Check existing keys in that file first by searching for the URL. If missing, fetch the actual context document from its canonical URL and add an entry:

"https://example.com/ns/v1": {
  "@context": {
    // ... paste actual context content here ...
  },
},

The keys of preloadedContexts must match the URL strings used in YAML defaultContext fields. This enables offline JSON-LD processing.

Complete minimal example

$schema: ../../vocab-tools/schema.yaml