[Compatibility] Version and publish schemas for all public JSON contracts

[cssbruno]

[Compatibility] Version and publish schemas for all public JSON contracts

Priority

High — machine-readable compatibility and ecosystem safety

Context

GOWDK exposes many JSON outputs intended for CI, editor tooling, generated runtimes, deployment tooling, and user inspection. Examples include:

• routes and endpoint manifests;
• asset manifests;
• build reports and timing reports;
• compiler manifests;
• inspect tree, IR, endpoint graph, asset graph, and Go binding reports;
• contract list/graph/trace reports;
• sitemap/editor reports;
• doctor, clean, audit, and version output;
• OpenAPI and AsyncAPI documents;
• security manifest/audit report output.

Several formats carry an integer version field, and audit/security outputs already have explicit JSON schemas. Most other machine-readable contracts do not appear to have a published schema, a compatibility policy, or a single validation gate across fixtures and command output.

Problem

A numeric version field alone does not define a stable contract. Without published schemas and compatibility rules:

1. Editors, CI scripts, deployment tooling, and external integrations must infer structure from examples or source code.
2. Optional/required/nullability semantics are unclear.
3. Breaking changes can occur without a deliberate version transition.
4. Multiple commands can use inconsistent field casing, source-reference shapes, or enum spelling.
5. Golden tests prove repository expectations but not conformance to a public machine-readable contract.
6. Runtime readers may silently accept incompatible or malformed manifests.
7. Users cannot validate archived build metadata independently of the compiler version that produced it.
8. Future gowdk changes, build verification, and artifact identity features lack a portable input contract.

Goal

Define, publish, validate, and document versioned schemas for every public or cross-process JSON contract, with explicit compatibility and lifecycle rules.

Contract inventory

Create an authoritative registry that classifies each JSON format:

• Public stable machine contract: intended for external tools and receives compatibility guarantees.
• Public experimental machine contract: externally visible but may evolve under documented 0.x rules.
• Internal generated-runtime contract: exchanged between compiler-generated artifacts and runtime, version checked but not general-purpose API.
• Debug-only output: human/developer aid with no compatibility guarantee; must be labeled accordingly.

The inventory should include at least:

Contract	Producer	Consumers	Current version	Stability
gowdk-routes.json	buildgen	runtime, adapters, tools	1	TBD
gowdk-assets.json	buildgen	runtime, deployment	2	TBD
gowdk-build-report.json	buildgen	CI, users	1	TBD
gowdk-build-timings.json	CLI	CI, profiling	1	TBD
compiler manifest	compiler/CLI	tools	current	TBD
inspect tree/graphs	CLI	editor/tools	current	TBD
Go bindings report	CLI/LSP	editor/tools	current	TBD
contract reports	CLI	tools	current	TBD
clean/doctor/version JSON	CLI	scripts	current	TBD
audit/security schemas	audit	CI/tools	existing	public experimental/stable decision

Do not mark every debug output stable merely because JSON exists. The value is in making the boundary explicit.

Schema organization

Store schemas in a predictable versioned tree, for example:

schemas/
  registry.json
  routes/v1.schema.json
  assets/v2.schema.json
  build-report/v1.schema.json
  build-timings/v1.schema.json
  compiler-manifest/v1.schema.json
  inspect-tree/v1.schema.json
  endpoint-graph/v1.schema.json
  go-bindings/v1.schema.json
  contracts-graph/v1.schema.json
  doctor/v1.schema.json
  clean/v1.schema.json
  version/v1.schema.json

Schemas should use a consistent JSON Schema draft and stable $id values. The repository should document whether $id URLs are publication URLs, identifiers only, or both.

Shared schema definitions

Create reusable definitions for recurring concepts:

• schema/version metadata;
• source file and source span;
• related locations;
• diagnostic severity/code/message;
• route and method;
• package/symbol identity;
• artifact relative path/hash/size/cache policy;
• build/plan identity;
• target and role;
• duration and counters.

Avoid duplicating subtly different span or diagnostic shapes across commands unless the difference is intentional and documented.

Compatibility policy

Document rules such as:

Within one schema major version

Allowed:

• adding optional fields;
• adding enum values only where consumers are required to handle unknown values;
• loosening a constraint when safe for consumers;
• clarifying descriptions without changing validation.

Requires a new version:

• removing or renaming fields;
• changing field types or required status;
• changing semantic meaning;
• narrowing accepted values;
• changing path/hash/source-span interpretation;
• changing unknown-field behavior where it affects consumers.

Each contract should state whether consumers must ignore unknown fields and how unsupported versions fail.

Because GOWDK is 0.x, schemas may evolve quickly, but evolution must be explicit rather than accidental.

CLI support

Add schema discovery and validation commands consistent with existing CLI conventions:

gowdk schema list
gowdk schema show routes@1
gowdk schema show assets@2 --json
gowdk schema validate gowdk-routes.json
gowdk schema validate --type build-report@1 report.json

schema validate should:

• identify the contract automatically when reliable metadata is present;
• allow explicit type/version selection;
• return stable exit codes;
• report JSON Pointer paths and concise remediation;
• avoid network access by using embedded schemas;
• support machine-readable diagnostics.

Embedding schemas in the CLI/runtime must not force optional heavy validation dependencies into the root runtime unless justified. Code-generated validators or a compiler-only validator may be preferable.

Producer validation

Every producer should validate its output in tests. Release/CI gates should validate:

• golden fixtures;
• representative real command output;
• generated example manifests/reports;
• schemas themselves for meta-schema validity;
• schema registry references and $id uniqueness.

Where performance permits, debug/test builds may validate generated JSON at production boundaries. Normal release builds should not require expensive redundant validation if construction through typed records already guarantees conformance.

Consumer behavior

Runtime and tooling consumers should:

• reject unsupported major versions clearly;
• distinguish missing, malformed, and incompatible files;
• avoid silently replacing malformed required manifests with empty data;
• preserve forward-compatible unknown optional fields where relevant;
• expose version mismatch through actionable diagnostics and health/readiness when it affects serving.

Strict runtime bundle validation may be tracked separately, but schema-version checks belong to this contract work.

Documentation and publication

• Link every JSON-producing command/reference page to its schema.
• Provide compact examples generated from current fixtures.
• Explain stability classification and unknown-field policy.
• Publish schemas with releases and, when the docs site is available, at stable versioned locations.
• Include schema changes in release notes.
• Record deprecated schema versions and support windows.

Generated language bindings

As a later or optional slice, generate Go types/validators and potentially TypeScript types for editor/tooling consumers from schemas or from the canonical Go definitions. Do not make npm mandatory for the core build.

The first implementation should prioritize schemas and validation rather than committing to a multi-language code-generation platform.

Test plan

• every schema validates against the chosen meta-schema;
• every registered fixture validates against its declared schema;
• missing required fields fail with stable paths;
• unknown fields follow each contract's documented policy;
• unsupported versions produce explicit errors;
• cross-platform paths are represented consistently;
• schema registry has no duplicate names, versions, or $id values;
• CLI list, show, and validate behavior is deterministic;
• offline validation works;
• runtime/compiler consumers reject incompatible required manifests;
• additive compatible fixtures continue validating under the same version;
• deliberately breaking fixture changes require a version update in tests.

Non-goals

• Declaring every internal/debug structure stable.
• Replacing OpenAPI or AsyncAPI with custom schemas.
• Requiring network access to validate generated artifacts.
• Introducing a mandatory npm/Node dependency for normal builds.
• Guaranteeing indefinite support for every 0.x schema version.

Acceptance criteria

• An authoritative registry lists every public/cross-process JSON contract and its stability class.
• Versioned JSON Schemas exist for all contracts classified as public or runtime-required.
• Shared definitions keep source spans, diagnostics, artifacts, and identity fields consistent.
• Compatibility and unknown-field rules are documented.
• CI validates schemas, fixtures, and representative command outputs.
• Breaking schema changes require an explicit version transition.
• gowdk schema list/show/validate works offline with stable exit behavior.
• Required runtime consumers reject unsupported versions with actionable errors.
• Reference documentation links outputs to their schemas.
• Release notes identify added, changed, deprecated, and removed schema versions.
• The implementation does not add a mandatory npm dependency or unnecessary root-runtime weight.

Related

• [Supply Chain] Pin privileged workflow inputs and harden installer bootstrap #640 — release reproducibility and supply-chain hardening
• Introduce phase-typed validated program and application plan boundaries #667/Split gwdkir.Program into semantic IR and target-specific plans #668 — canonical semantic/application plan
• Publish build and generated-app output transactionally #669 — transactional artifact publication
• Extract shared project compilation orchestration from the CLI #671 — shared compilation orchestration
• Version and harden the executable addon bridge #672 — versioned addon protocol
• Define and enforce the v1 core versus optional product boundaries #677 — stability/product boundaries
• deterministic build identity issue
• gowdk changes issue