Skip to content

P2.SPC.010 — Tool ships a versioned JSON output schema

Field Value
Principle P2 (Spec-first)
Pack agent-tool
Severity warn
Evidence strong
Stability experimental

What it checks

The rule verifies spec-first practices. It fires when:

  1. No *.schema.json files exist under schemas/ and no alternative spec formats are found (OpenAPI, Protobuf, GraphQL, Avro).
  2. *.schema.json files exist, but none declares a top-level $id.

Recognized spec-first formats (any of these suppress the "no schemas" finding): - JSON Schema: schemas/*.schema.json - OpenAPI: openapi.yaml, openapi.yml, openapi.json, swagger.yaml, swagger.json - Protobuf: *.proto files - GraphQL: *.graphql, *.gql files - Avro: *.avsc files

In addition, any file that fails to parse as JSON produces a separate parse_failure finding (see evidence.parse_failure) so agents don't confuse a broken schema with a missing one.

Why it matters

Agent-driven tools are contracts. An output contract without a stable, discoverable identifier is a contract that consumers cannot pin to. The first time the tool changes output shape, downstream agents break silently. $id plus a schema_version field in the output are the cheapest possible stability signal.

When to care

  • Care always when the tool emits structured output intended for programmatic consumption.
  • Care less for internal-only scripts. Suppress with a rationale.

How to fix

  1. Put the schema at schemas/output.schema.json (or a pattern-matching name).
  2. Give it a top-level $id like https://yourorg.example/schemas/output.schema.json.
  3. Include a schema_version field in your tool's emitted output.
  4. Document the compatibility promise (additive changes bump minor, renames/removals bump major).

See also

  • docs/rules/P7.MRD.001.md — CLIs should document exit codes.
  • archfit's own schemas/output.schema.json as a template.