[OmarAlJarrah]

Summary

OpenAPI 3.2 adds components/mediaTypes and lets a content entry be a Reference Object to one of its entries. The parser models neither, so the compiler never followed such a reference: the entry lowered with no schema, and the $ref and the whole section were kept verbatim with a warning. This follows them, designed against the four defects #856 records of a first attempt.

• Resolved where every reference is. The load phase models each components/mediaTypes entry, and each content entry written as a $ref, as the parser's generic reference over a Media Type Object (resolve.ReferencedMediaType), walks them with the source, and hands them to the parser's resolver as it hands every other reference object: under the same reader, budgets and refusals, with what they reach held to the rule table. A content entry written as a $ref inside another document is followed too.
• One declaration, one type. What a reference reaches lowers once, at the pointer declaring it, named for its components/mediaTypes key, however many content entries reach it (request and response bodies, content-style parameters and headers) and in whichever order they lower. The binder learns the section, so a schema $ref inside an entry, or into one, is bound where it is declared.
• References inside the entry resolve. A chain ends on the model the load phase walks, not on a copy the resolver builds, so an example, an encoding header or a schema $ref inside the entry lowers with what it names.
• Chains of entries are followed as any reference chain is, and a cycle among them is reported as one among other reference objects is.
• Siblings beside the $ref. ir.Content gains Docs: a 3.2 Media Type Object's description, kept verbatim until now, and the summary and description beside a $ref to it, folded along the chain as every other position folds them. A content-style parameter or header, whose carrier has no docs field for its media type, keeps what the fold takes verbatim, each from the position writing it.
• Retention. An entry nothing references joins the retained components as openapi:components/mediaTypes/<name>, and the whole-section entry and both warnings go.

Two library behaviours made this more than a new alias. Both are recorded as docs/parser-library.md#media-type-references and pinned by a canary. The library's walk panics on a reference type it has no handler for, so the load phase yields these models itself. The resolver cannot take the model's own Media Type Object for a reference, so a $ref to an inline content entry would fail. The load phase holds each of the source's Media Type Objects where the resolver looks before reading the model, and resolves the source's media type references once its walk has held them all, so such a $ref reaches its target, under $self too.

Out of scope, each filed with every site of its mechanism and stated at the code and rule that have it. The first three are shared with every other kind of reference object, and a content entry joins them by being read as one: on main such an entry lowered as written, with the warning that its $ref was not followed.

• openapi: a plain date at a string field reads as empty, with no diagnostic #1280: a reference object whose $ref the model decodes no string from, such as a plain date or a scalar under a local tag, lowers nothing, and nothing reports it. A content entry written so now does the same.
• openapi: a reference object inside an object reached in raw YAML is never resolved #1320: a reference object inside an object a $ref reaches in the source's raw YAML is never resolved. A media type reference inside such an object shares it, and its entry lowers no Content.
• openapi: a key beside a reference object's $ref is dropped with no record #1321: a key beside a reference object's $ref, other than summary and description, is dropped with no record. Content entries written as a $ref now share it with every other kind.
• openapi: a reference object whose pointer ends in '/' interns its target twice #1330: a reference object whose pointer ends in / and lands on raw YAML interns its target twice. Since the parser reads components/mediaTypes as raw YAML, #/components/mediaTypes/Pet/ is one such pointer.
• openapi: a schema $ref through a reference object's alias interns the schema twice #1359: a schema $ref whose pointer passes through a reference object's alias lowers what it reaches a second time, at the pointer it spells. Every kind does this on main; a pointer through a components/mediaTypes alias now does too, where main reported it unresolved.
• openapi: a parameter and its schema share one Unmodeled namespace #396: a carrier shares one Unmodeled namespace with what it lowers. At a parameter's or header's content entry, a summary the media type's declaration writes, which a Media Type Object does not define, loses its entry to the one the fold takes from the use site or an alias, and is reported as represented in no form; a body keeps both.

#1229 landed with IRVersion 0.27.0 and #1325 with 0.28.0, so this change takes 0.29.0. #1269 also claims 0.27.0 from an older base; whichever of the two merges later takes the next version.

Closes #856

Breaking

IRVersion moves to 0.29.0, and a consumer pinned to 0.28.0 refuses the documents this version writes. Content gains docs. A Media Type Object's description moves from Content.Unmodeled["openapi:description"] to Content.Docs.Description; a content entry written as a $ref lowers what it names and no longer carries openapi:$ref; and Document.Unmodeled["openapi:components/mediaTypes"] gives way to one entry per entry nothing references.

Test plan

• operation: one declaration lowers to one type in both declaration orders, for a component of the source and of another document and for an inline content entry, with and without a reader; references inside the declaration resolve; docs fold along an alias chain at a body and at a parameter, and one an alias in another document writes is reported; a body's Content.Docs and what a parameter keeps agree over every spelling of each key (left out, empty, null, text) at the use site, the alias and the declaration; a parameter and a header naming a media type in another document read its schema there, placing what they keep verbatim in that document and leaving a bound on the schema's own node; an unresolved reference lowers nothing; a $ref holding no string draws one finding.
• load: the section's entries are modelled as the parser reads it; the source's walk yields each model once; a chain ends on the declaration's own model, by the key the resolver uses, under $self, and through a spelling that key misses; a fault building a reference is reported once, in whichever document writes it; what a reference reaches in another document is judged by the rule table.
• e2e: a source rebuilt for an anchored document it reads lowers a reference into that document as a source not rebuilt does.
• canary: TestLibraryBehaviour/media-type-references.
• Conformance: component-media-types-32 rewritten to exercise the feature; the later-version-constructs and unreferenced-components goldens regenerated.
• Each guard was mutated and the tests above went red: the cache hold, the deferred resolution, the canonical model, the census key, the binder's section and reference kind, the docs fold, the unset reading, the declaration's summary, the naming, the retention, the fault report, the reached object's kind, the rebuild's modelling, and the context each content-style carrier reads its schema in, at all four calls.
• The golden spec (cloudflare/api-schemas @319dc756) compiles to byte-identical IR and diagnostics against main, irVersion aside, as do the five OpenAPI 3.2 specs of a real-world spec corpus. Over every spec under testdata and that corpus, 2,181 in all, only the three conformance cases this change rewrites differ from main, with the same exit codes (9c3065c against 02c972b).
• After merging feat(ir)!: type the secrecy and stability a document states #1229: a parameter and a header whose content $ref names a media type in another document, whose schema is deprecated and x-sensitive, are marked as ones naming that schema directly are.
• Cost, measured at a load average near 60. On a 3.7 MB OpenAPI 3.0 spec using no media type reference, CPU profiles put about 0.25% of compile time in the new walk step, and the functions this change adds allocate under 1% of the bytes. Instructions retired, one thread with the collector off, read 1.2% to 1.6% above main there; the largest difference between the two builds' profiles is the runtime returning memory to the OS rather than compiler code, and such counts include that work, which moves with the machine's memory pressure. Content references scale linearly, about 3.95M instructions per operation of three references from 500 to 4,000 operations, and cost under a quarter of the same entries written inline, since a declaration lowers once.
• CI runs the gate.