Přeskočit obsah

Schema Metadata Convention

This directory keeps JSON Schema as the canonical machine-readable boundary contract.

We also use lightweight schema metadata to carry semantic meaning close to the fields without changing validation behavior.

Preferred metadata

description

Use description for the primary semantic meaning of:

  • the whole schema,
  • a field,
  • a nested object,
  • a reusable $defs entry.

description should explain what the field means in the Orbiplex domain, not only its syntax or storage shape.

$comment

Use $comment for short author-side notes that help maintainers but are not required for end-user documentation. Validators may ignore this field.

Typical use cases:

  • local modeling caveats,
  • migration notes,
  • why a constraint exists,
  • reminders about non-obvious edge cases.

x-dia-basis

Use x-dia-basis as an Orbiplex-specific extension that links a schema or a field to the normative or operational documents that define its semantics.

Recommended shape:

{
  "x-dia-basis": [
    "doc/normative/40-constitution/CONSTITUTION.md",
    "doc/normative/50-constitutional-ops/UNIVERSAL-BASIC-COMPUTE.md"
  ]
}

Notes:

  • paths should be repository-relative, from /orbidocs,
  • short ids from doc/_refs.toml may be used when a document is referenced by many related schemas,
  • prefer the most direct governing sources,
  • keep the list short and specific.

Shared definitions

Schemas that need common vocabulary MAY use small shared schemas under doc/schemas/_shared/. Shared schemas are contracts too: they are validated, included in generated schema docs, and synchronized to node/protocol/contracts/schemas/_shared/.

Use shared definitions for stable enum families that would otherwise drift across several security-sensitive contracts. Do not put domain policy prose or executable policy in _shared; keep it to reusable data definitions.

Authoring rule

Use metadata only where it adds semantic clarity.

Do not turn schema files into prose-heavy documents. The schema should remain readable as a contract first. Richer narrative belongs in the governing markdown documents.

Practical rule of thumb

  • put the core meaning in description,
  • put traceability in x-dia-basis,
  • put maintainer-only notes in $comment.