Skip to content

feat(schemas): v0.1.0 meta-schemas + CI validation (#123, #124)#199

Merged
zeevdr merged 1 commit into
mainfrom
meta-schema-v0.1.0
Apr 27, 2026
Merged

feat(schemas): v0.1.0 meta-schemas + CI validation (#123, #124)#199
zeevdr merged 1 commit into
mainfrom
meta-schema-v0.1.0

Conversation

@zeevdr
Copy link
Copy Markdown
Member

@zeevdr zeevdr commented Apr 27, 2026

Closes #123. Closes #124.

Summary

Two single-file JSON Schema 2020-12 meta-schemas under `schemas/v0.1.0/`:

  • `decree-schema.{yaml,json}` — validates the schema-definition format (`*.decree.schema.yaml`)
  • `decree-config.{yaml,json}` — validates the tenant-side config format (`*.decree.config.yaml`)

Plus a Python validation harness (`scripts/validate-meta-schemas.py`) wired into CI as a new "Meta-schemas check" job, closing #124. The script asserts every checked-in canonical file passes the matching meta-schema and every fixture under `schemas/v0.1.0/testdata/invalid/` fails (proves the meta-schema actually rejects what it claims to). 17 invalid fixtures cover the full failure surface.

Departure from the schema-spec brief

The brief originally specified split-file YAML sources (OpenAPI-style: `field.yaml`, `constraints.yaml`, `info.yaml`, etc.) bundled to a single JSON artifact. The format proved small enough that splitting cost more than it saved — single-file with internal `$defs` is more idiomatic and easier to read. `schema-spec.md` updated to reflect.

What's covered

The schema meta-schema covers the full v0.1.0 reserved-key surface, including:

YAML→JSON

`scripts/yaml-to-json.py` is a 30-line Python script that converts the human-edited YAML sources to JSON. Both forms are committed alongside each other so consumers (schemastore.org, IDE language servers, CI validators) can `$ref` the JSON directly without a build step.

Test plan

  • All canonical `.decree.schema.yaml` and `.decree.config.yaml` files in the repo pass.
  • All 17 known-invalid fixtures fail with messages pointing at the offending path.
  • `make validate-meta-schemas` runs the script locally.
  • New CI "Meta-schemas check" job runs unconditionally (no `needs.changes` gate) so docs-only PRs still validate; included in the `CI check` aggregate gate.
  • Legacy `schemas/schema-yaml.json` removed; `docs/concepts/schemas-and-fields.md` modeline updated to point at the new file.

Out of scope

Closes #123, closes #124.

Adds two single-file JSON Schema 2020-12 meta-schemas under
schemas/v0.1.0/ — decree-schema.{yaml,json} validates the
schema-definition format, decree-config.{yaml,json} validates the
tenant-side config format. Both use internal $defs only; YAML is the
human-edited source, JSON is generated by scripts/yaml-to-json.py and
committed alongside for tooling consumers (schemastore.org, IDE
language servers) that prefer JSON.

The schema meta-schema covers the full v0.1.0 reserved-key surface
including the dependentRequired and validations keys landed in #193 /
#192. The 4-branch per-type constraint matrix (numeric / string / json
/ other) uses allOf [if/then] rather than oneOf — better error messages
in ajv and python-jsonschema. unevaluatedProperties: false at every
object level (works correctly with allOf composition); patternProperties
"^x-" allows vendor extensions everywhere.

Departs from the schema-spec brief's original "split files + bundling
script" plan: the format is small enough that splitting cost more than
it saved. Single-file with internal $defs is more idiomatic and easier
to read. schema-spec.md updated to reflect the revised approach.

Validation harness:
- scripts/validate-meta-schemas.py asserts every checked-in
  *.decree.schema.yaml and *.decree.config.yaml passes the matching
  meta-schema, AND every fixture under schemas/v0.1.0/testdata/invalid/
  fails (proves the meta-schema actually rejects what it claims to).
  17 invalid fixtures cover unknown keys, bad spec_version, bad slug,
  bad field paths, unknown field types, wrong constraints per type,
  empty rule/message in validations, bad severity, malformed
  dependentRequired keys, missing required keys, etc.
- make validate-meta-schemas runs the script locally.
- New CI job "Meta-schemas check" runs unconditionally (no
  needs.changes gate) so docs-only PRs still validate.

Removes the legacy schemas/schema-yaml.json (single-file pre-v0.1.0
meta-schema, missing the new reserved keys). docs/concepts/schemas-and-
fields.md updated to reference the new files.

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 server Server changes ci CI/Infrastructure docs Documentation size: M Moderate — a day or two, clear scope priority: P0 Blocks alpha or release labels Apr 27, 2026
@zeevdr zeevdr merged commit f3278d5 into main Apr 27, 2026
19 checks passed
@zeevdr zeevdr deleted the meta-schema-v0.1.0 branch April 27, 2026 16:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci CI/Infrastructure docs Documentation priority: P0 Blocks alpha or release server Server changes size: M Moderate — a day or two, clear scope

Projects

None yet

Development

Successfully merging this pull request may close these issues.

CI: validate schema YAMLs against meta-schema Author meta-schema v0.1.0 (JSON Schema 2020-12)

1 participant