The compat engine ignores examples, nested schema description, and arbitrary x-* extensions. A push that only improves examples or fixes descriptions gets an empty compat report, even though the registry still bumps the patch version. Consumers and CI cannot see what changed.
This is currently documented as out of scope in docs/registry/compat-classification.md:284 and explicitly tested in tests/registry/unit/compat/differ.test.ts:853-1013. The engine already detects operation-level metadata like summary, description, and tags as safe documentation changes. We should extend that same treatment to schema-level examples, descriptions, and non-structural extensions.
Goal: emit safe documentation-updated changes for these metadata edits so they appear in compat reports without changing semver classification (still patch).
Components: compat engine (src/registry/compat-engine/differ.ts), CLI output (src/cli/output.ts), tests, docs.
Expected behavior: a push that only adds a response schema example should produce a visible safe change in grapity registry push output instead of an empty report.
The compat engine ignores
examples, nested schemadescription, and arbitraryx-*extensions. A push that only improves examples or fixes descriptions gets an empty compat report, even though the registry still bumps the patch version. Consumers and CI cannot see what changed.This is currently documented as out of scope in
docs/registry/compat-classification.md:284and explicitly tested intests/registry/unit/compat/differ.test.ts:853-1013. The engine already detects operation-level metadata likesummary,description, andtagsas safe documentation changes. We should extend that same treatment to schema-level examples, descriptions, and non-structural extensions.Goal: emit safe
documentation-updatedchanges for these metadata edits so they appear in compat reports without changing semver classification (stillpatch).Components: compat engine (
src/registry/compat-engine/differ.ts), CLI output (src/cli/output.ts), tests, docs.Expected behavior: a push that only adds a response schema example should produce a visible safe change in
grapity registry pushoutput instead of an empty report.