Skip to content

docs(concepts): schema-format.md + meta-schema.md (#127)#200

Merged
zeevdr merged 1 commit into
mainfrom
docs-schema-format
Apr 27, 2026
Merged

docs(concepts): schema-format.md + meta-schema.md (#127)#200
zeevdr merged 1 commit into
mainfrom
docs-schema-format

Conversation

@zeevdr
Copy link
Copy Markdown
Member

@zeevdr zeevdr commented Apr 27, 2026

Closes #127.

Summary

Graduates the internal `.agents/context/schema-spec.md` design brief into public, maintained user-facing documentation. Two new docs under `docs/concepts/`:

  • `schema-format.md` — canonical reference for the `decree.schema.yaml` format. Every top-level key, every field-level option, every constraint with the per-type compatibility matrix, the `dependentRequired` and `validations` cross-field rule mechanisms, the field-path and slug regexes, recommended `format:` values (advisory list), import/export semantics, strict mode, vendor extensions.

  • `meta-schema.md` — what the JSON Schema 2020-12 meta-schemas under `schemas/v0.1.0/` cover (layer 1) vs non-goals (layer 2 semantic rules stay Go-side). URL scheme + SemVer + stability policy. How to wire the meta-schema into editor tooling (yaml-language-server modeline) and CI / programmatic validators (check-jsonschema, ajv, santhosh-tekuri/jsonschema).

Reorganization

`schemas-and-fields.md` is trimmed to be the higher-level concepts overview — lifecycle, drafts vs published versions, quick example, brief intros to types and cross-field rules — and cross-links out to `schema-format.md` (full reference) and `meta-schema.md` (mechanical validation). The full format reference content moved to `schema-format.md`.

Other updates

  • `docs/getting-started.md` — uses the canonical `decree.schema.yaml` filename + the `# yaml-language-server: $schema=...` modeline on line 1 of the schema example.
  • `README.md` — new section under the API table linking to `schema-format.md` + `meta-schema.md` and the published meta-schema URLs.
  • `mkdocs.yml` — adds the two new docs to the Concepts nav.
  • `typed-values.md` — fixes the orphaned anchor link to point at `schema-format.md#constraints` (the heading moved with the content).

Test plan

  • `make validate-meta-schemas` passes (no schema YAMLs touched, but the script runs as a regression check).
  • All internal cross-links manually verified to land on existing headings.
  • mkdocs nav updated; new docs render cleanly in the Material theme.
  • CI "Docs check" should pass — only Markdown changes, no proto/sqlc regeneration needed.

Out of scope (follow-ups)

Closes #127.

Graduates the internal `.agents/context/schema-spec.md` design brief
into public, maintained user-facing documentation. Two new docs:

- `docs/concepts/schema-format.md` — canonical reference for the
  decree.schema.yaml format. Every top-level key, every field option,
  every constraint with the per-type compatibility matrix, the
  dependentRequired and validations cross-field rule mechanisms, the
  field-path and slug regexes, recommended `format:` values (advisory
  list), import/export semantics, strict mode.

- `docs/concepts/meta-schema.md` — what the JSON Schema 2020-12
  meta-schemas under `schemas/v0.1.0/` cover (layer 1) vs non-goals
  (layer 2 semantic rules stay Go-side). URL scheme + SemVer +
  stability policy. How to wire the meta-schema into editor tooling
  (yaml-language-server modeline) and CI (check-jsonschema, ajv,
  santhosh-tekuri/jsonschema).

Trims `docs/concepts/schemas-and-fields.md` to be the higher-level
concepts overview — lifecycle, drafts vs published versions, quick
example, brief intros to types and cross-field rules — and
cross-links out to schema-format.md and meta-schema.md for full
reference details.

Updates `docs/getting-started.md` to use the canonical
`decree.schema.yaml` filename and the
`# yaml-language-server: $schema=...` modeline. Updates README.md to
link the new format reference and the published meta-schema URLs.
Adds the new docs to mkdocs.yml nav.

Fixes the now-orphaned anchor link from typed-values.md to point at
schema-format.md#constraints.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@zeevdr zeevdr added this to the Schema Spec v0.1.0 milestone Apr 27, 2026
@zeevdr zeevdr added docs Documentation size: M Moderate — a day or two, clear scope priority: P0 Blocks alpha or release labels Apr 27, 2026
@github-actions
Copy link
Copy Markdown

Thanks for your first pull request! We appreciate the contribution.

Before review, please make sure:

  • make all passes (generate, lint, test, build)
  • The PR targets main and has a clear description
  • See CONTRIBUTING.md for the full checklist

@zeevdr zeevdr merged commit 2fe0fa4 into main Apr 27, 2026
18 checks passed
@zeevdr zeevdr deleted the docs-schema-format branch April 27, 2026 17:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation priority: P0 Blocks alpha or release size: M Moderate — a day or two, clear scope

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: schema-format, meta-schema, modeline, README

1 participant