Repository navigation
openapi: the default promotion mapping covers only deprecation and extensible enums #656
Description
Problem
docs/ir/unmodeled.md#promotion gives several typed fields whose only OpenAPI spelling is a vendor extension, and makes reading them injectable policy that is on by default. The default mapping (DefaultExtensionPromotions) covers four keys, for Deprecation and Enum.Closed. Specs in the wild state more than that through a small set of widely used extensions, and all of it reaches the IR today only as Unmodeled entries:
| Fact | Typed home | What the extension values look like |
|---|---|---|
| Pagination | Operation.Pagination |
a strategy (cursor, offset/limit, next URL), the inputs that feed it, and JSONPath-style expressions for results and continuation |
| Open enum stated by value | Enum.Closed |
allow/disallow (#654 first) |
| Deprecation message | Deprecation.Message |
a string beside deprecated: true |
| Reserved expansion on a parameter | HTTPParamBinding.AllowReserved |
an encoding override on the parameter |
| Sensitive values | Property.Secret / Sensitive |
a boolean on a property or parameter (#578) |
| Server identity | Server.Name |
a string on each server (#672 first) |
For pagination, not every declared configuration fits ir.Pagination: inputs that live in the request body, array selectors such as "the last element", a page-count output, and paths through unions or maps have no home (#665). A path that doesn't resolve through the response schema to PropIDs is reported and the field left nil.
Proposal
Choose the default keys per row, following the rules of docs/ir/unmodeled.md#promotion (value-aware readers, reported misfits, Inferred recorded). Keys that name a field on another node (the binding, a flow, the server) need #674 settled first.
Activity
docs: state each limit of a promotion where it lives
OmarAlJarrah commentedon Nov 2, 2026
#1376 (open) adds the promotion target
deprecation.replacedBy, fillingDeprecation.ReplacedBywith the entity a mapped key names as a deprecated node's replacement: anoperationIdon an operation, a parameter's name on a parameter, a component name on a schema, and so on per class. It ships with no default key, asunion.opendoes: the golden spec writes no key naming a replacement (api-schemas @319dc756), and across 1,840 OpenAPI 3 specs in a real-world corpus one convention appears, in 2 test specs. A default is this issue's to choose once a key is in common use; the reading it would apply is already the target's.