> For the complete documentation index, see [llms.txt](/llms.txt)

# 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.