noy-db
experimental

Metadata ladder

The collection and vault rungs above field-level metadata — collectionMeta and vaultMeta identity layers that describe() and dumpSchema() surface for viewers.

Above field-level metadata sit two more rungs — collection and vault identity — that viewers consume without duplicating their own label logic.

The field-level descriptors (fieldMeta / DescribedField) are the bottom rung of a three-rung metadata ladder:

field  →  collection  →  vault

Each rung adds a friendly identity layer that viewers (devtools, editor, export filename, API doc) consume without duplicating their own label logic.

collectionMeta

Declare via the meta collection option:

const invoices = vault.collection<Invoice>('invoices', {
  meta: {
    label: 'Sales Invoices',
    description: 'Outbound sales invoices billed to clients.',
    pluralLabel: 'Sales Invoices',  // for list headers
    icon: 'receipt',                // semantic icon name (Lucide etc.)
  },
  fieldMeta: { … },
})

CollectionMeta members:

FieldTypePurpose
labelstring?Friendly collection name; falls back to the humanized collection name
descriptionstring?Longer tooltip / context
iconstring?Semantic icon name (e.g. a Lucide key), not styling
pluralLabelstring?Plural form for list headers ("Invoice" → "Invoices")

Unlike FieldMeta.label, CollectionMeta.label is optional — the collection name is already a reasonable fallback identity.

First-wins reconciler. When a collection is pre-created by an MV before the app's own vault.collection() call, the first declared meta wins (mirrors _applyFieldMeta).

Surfaces in:

  • collection.describe() → CollectionDescription.meta
  • vault.dumpSchema() → CollectionDescriptor.meta
  • in-devtools snapshot() → InspectorCollection.meta

vaultMeta

Declare via the meta vault option:

const vault = await db.openVault('ledger', {
  meta: { label: 'Acme Ledger 2026', description: 'Main accounting vault.' },
})

VaultMeta members:

FieldTypePurpose
labelstring?Friendly vault name; falls back to the vault name
descriptionstring?Longer context
iconstring?Semantic icon name

First-wins. Re-opening an already-cached vault keeps its meta.

Surfaces in:

  • vault.dumpSchema() → VaultSchemaSnapshot.meta
  • in-devtools snapshot() → InspectorSnapshot.meta

Cargo export. CollectionMeta and VaultMeta are also exported from @noy-db/hub/cargo (the klum orchestration seam) so that klum-db's federation layer can reuse VaultMeta for groupMeta without taking a full hub dep.

See also

manifest

Metadata riders