mdvdb logo mdvdb
Markdown source

mdvdb schema

Show the merged metadata schema for indexed Markdown documents. mdvdb infers fields from YAML frontmatter and applies optional definitions from .markdownvdb.schema.yml, including relations and computed fields.

Usage

mdvdb schema [--path <PREFIX> | --shard <ID>] [GLOBAL OPTIONS]
FlagDescription
--path <PREFIX>Restrict the schema to a relative folder prefix
--shard <ID>Use the folder configured for a named Shard

--path and --shard conflict. Without either option, the command returns the collection-wide schema. It also accepts all global options.

Examples

mdvdb schema
mdvdb schema --path invoices
mdvdb schema --shard operations
mdvdb schema --path invoices --json

Field types

JSON serializes these names in PascalCase:

TypeMeaning
StringText value
NumberInteger or decimal value
Booleantrue or false
ListYAML sequence
DateDate-shaped text such as 2026-08-06
MixedMore than one incompatible observed type
RelationWhole-value reference to another Markdown document
FileReference to a non-Markdown file
JsonStructured object or nested collection
FormulaDeterministic value calculated from the current document
LookupValue copied from a related document
RollupFormula evaluated over values collected from related documents

Schema overlay

The optional overlay adds annotations, type declarations, relation targets, and computed-field definitions. Global fields apply collection-wide; scopes apply to folder prefixes.

# .markdownvdb.schema.yml
fields:
  status:
    description: Document lifecycle status
    allowed_values: [draft, review, published]
    required: true

scopes:
  invoices:
    fields:
      client:
        field_type: relation
        target: clients
      total:
        field_type: formula
        formula: price * quantity
        result_type: number
      client_domain:
        field_type: lookup
        relation_field: client
        target_field: domain
      related_total:
        field_type: rollup
        relation_field: related_invoices
        target_field: total
        formula: values.reduce((sum, value) => sum + Number(value), 0)
        result_type: number

Incoming Rollups additionally use relation_direction: incoming and relation_scope to select the source folder. Lookup traversal is always outgoing.

After changing the overlay, run an unscoped mdvdb ingest to refresh persisted schemas and materialized computed values.

JSON output

Unscoped output is a Schema:

{
  "fields": [
    {
      "name": "client",
      "field_type": "Relation",
      "description": null,
      "occurrence_count": 18,
      "sample_values": ["[[clients/acme]]"],
      "allowed_values": null,
      "required": false,
      "relation_target": "clients",
      "formula": null,
      "result_type": null,
      "relation_field": null,
      "target_field": null,
      "relation_direction": null,
      "relation_scope": null
    },
    {
      "name": "total",
      "field_type": "Formula",
      "description": null,
      "occurrence_count": 18,
      "sample_values": ["125.00", "240.00"],
      "allowed_values": null,
      "required": false,
      "relation_target": null,
      "formula": "price * quantity",
      "result_type": "Number",
      "relation_field": null,
      "target_field": null,
      "relation_direction": null,
      "relation_scope": null
    }
  ],
  "last_updated": 1770000100
}

Scoped output wraps the same structure:

{
  "scope": "invoices/",
  "schema": {
    "fields": [],
    "last_updated": 1770000100
  }
}

SchemaField keys

KeyDescription
name, field_typeColumn name and resolved type
description, allowed_values, requiredOverlay annotations
occurrence_count, sample_valuesInferred/materialized field statistics
relation_targetDeclared target folder for a Relation
formula, result_typeFormula/Rollup expression and declared output type
relation_field, target_fieldRelation to follow and exact field to copy/aggregate
relation_directionOutgoing or Incoming for Lookup/Rollup definitions
relation_scopeSource folder used by an incoming Rollup

Optional metadata keys are always present and serialize as null when not applicable.

Notes

  • schema is read-only; it does not evaluate or materialize fields.
  • Fields are ordered alphabetically and samples are capped at 20 values.
  • The human-readable view shows up to five samples and marks required fields.