The Glotto IR

GlottoIR is Glotto’s intermediate representation: the normalized, language-neutral model of your API that every codegen engine consumes. Spec ingest produces it once, and all 21 @glotto/codegen-* engines read the same GlottoIR — which is why the TypeScript, Python, Go, Swift, … SDKs stay structurally consistent.

Where it comes from

buildGlottoIR runs over the canonical spec (the byte-stable, normalized OpenAPI / AsyncAPI / GraphQL document produced by spec ingest) and applies the transforms from your glotto.yml. The output is a GlottoIR value; codegen never reads raw OpenAPI.

What it contains

• Resources — a tree (with subresources), derived from path segments, that becomes nested clients like client.pets.photos.
• Methods — per operation: http_method, path, parameters, request_body, responses, the detection flags paginated / streaming / polling, sample_inputs, and the captured prose (summary / description / x-glotto-mcp-prompt).
• Models — named types, including any discriminator for oneOf polymorphism.
• Auth, environments, and snippet seeds at the top level.

Transforms

glotto.yml#/transforms reshape an imperfect spec without editing the source — rename_schema, flatten_composition, dedupe_inline_objects, extract_ref, fix_invalid_example. Each is fail-fast: a transform whose target no longer exists raises a diagnostic instead of silently doing nothing.