Documentation article
What is Shape IR?
Shape IR is the shared semantic layer that keeps multi-format transformation work coherent.
Shape IR is the shared representation that lets the toolkit reason about schemas without binding every feature to one source format.
It is not just an implementation convenience. It is the product concept that keeps parser, generator, and future analysis work aligned.
Parsers translate source-specific schemas into Shape IR. Generators consume Shape IR and render a target format. That means every new format extension can plug into a shared core instead of multiplying one-off adapters.
The result is a clearer architecture and a much better foundation for diagnostics, comparisons, and future analysis layers.
A good intermediate representation should feel narrower than every source format while still being expressive enough for the workflows you care about.
The real IR can grow beyond this sketch, but the core idea stays the same: preserve meaning in a reusable structure before targeting any specific output format.
A simplified Shape IR sketch
type Shape =
| {kind: "string"}
| {kind: "number"}
| {kind: "array"; element: Shape}
| {kind: "object"; fields: Record<string, Shape>};