Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/architecture/ir-types.md
Original file line number Diff line number Diff line change
Expand Up @@ -823,7 +823,7 @@ Wherever two inline models are folded into one by structural agreement — list-

**Source per node.** Each node reads `deprecated` from one place: `Operation` from the Operation Object's own keyword; `Parameter` from any of the Parameter Object (after a `components.parameters` `$ref` is resolved), its inline `schema` and the component schema its `schema.$ref` points at — deprecated when any of the three says `deprecated: true`, so a `false` on one level does not stop a `true` on another; `ResponseHeader` from the Header Object only (after a `components/headers` `$ref` is resolved), never from its schema; `Field` from the property schema itself, a keyword written beside a `$ref` included, while the referenced model keeps its own and an `allOf` member's is not read — or, for a bare `$ref` to an array component, which has no model to keep the flag, from the component as well (see Array components); `Model` and `Enum` from the schema's own top-level keyword as described above. At every site the parser tests `=== true`: a `false`, absent or non-boolean keyword (`"yes"`, `1`) leaves the key absent, so the IR never carries anything but a literal `true`, on any of the six nodes. `EnumValue.deprecated` reads the value's own `const` member — an enum declared as a `oneOf`/`anyOf` of `const` schemas — by the same `=== true` rule, and is absent on every value of a plain `enum:` list, which has no per-value keyword (see Enum below).

The differ compares the flag on every node that carries it — operation, parameter, response header, model, field, enum, enum value, webhook and webhook parameter — and reads it the way the parser writes it: only `true` is deprecated, so `false` and an absent key are the same thing, and a document that spells out `deprecated: false` diffs as unchanged against one that omits it. A flip is reported on the owning `-modified` change: `deprecatedChanged: true` on `operation-modified`, `model-modified`, `enum-modified` and `webhook-modified`, with `oldDeprecated`/`newDeprecated` beside it (present exactly when the flag is); a `param-deprecated-changed`, `header-deprecated-changed`, `field-deprecated-changed` or `value-deprecated-changed` entry, carrying the same two values and a `details` that reads `live → deprecated` or `deprecated → live`, in the change's `paramChanges`, `responseHeaderChanges`, `fieldChanges` or `valueChanges` for an operation's or a webhook's parameter, an operation's response header, a field or an enum value. A model, enum, operation or webhook whose only change is the flag is still reported, with an empty nested list. Becoming or ceasing to be deprecated changes no contract — the node is still there with the same shape — so every one of these is additive, in either direction; it still counts as `modified` in the summary, and a breaking change on the same node (a removed field beside the model's flag, a changed response beside the operation's, a retyped payload beside the webhook's) keeps the change breaking. Each flip is also mirrored into `behaviorChanges` as a `deprecated-changed` entry naming the node (`operation`, `parameter`, `response-header`, `model`, `field`, `enum`, `enum-value`, `webhook` or `webhook-parameter`) and copying `oldDeprecated`/`newDeprecated` from the change, the way a parameter default change is, so a changelog can say which way it went without reading both specs. Parameters are compared in every location a node carries them — an operation's path, query, header and cookie parameters, a webhook's header, query and cookie parameters — and matched by location and name, since a path `id` and a query `id` may sit on one operation and a webhook's header and query parameters may share a name — a header's name compared case-insensitively, so a header deprecated and respelled `x-pet-token` in one step is still the `X-Pet-Token` it was, and its flip is reported; every `paramChanges` entry carries `paramLocation` to say which one it is about. A response header's flag is compared on every response entry that declares headers — the primary and every other 2xx/3xx entry, every error, the `default` and every range — with headers matched by name case-insensitively, and every `responseHeaderChanges` entry carries its `statusCode` or `fallback` to say which entry it is about (see Response Headers above).
The differ compares the flag on every node that carries it — operation, parameter, response header, model, field, list envelope field, enum, enum value, webhook and webhook parameter — and reads it the way the parser writes it: only `true` is deprecated, so `false` and an absent key are the same thing, and a document that spells out `deprecated: false` diffs as unchanged against one that omits it. A flip is reported on the owning `-modified` change: `deprecatedChanged: true` on `operation-modified`, `model-modified`, `enum-modified` and `webhook-modified`, with `oldDeprecated`/`newDeprecated` beside it (present exactly when the flag is); a `param-deprecated-changed`, `header-deprecated-changed`, `field-deprecated-changed` or `value-deprecated-changed` entry, carrying the same two values and a `details` that reads `live → deprecated` or `deprecated → live`, in the change's `paramChanges`, `responseHeaderChanges`, `fieldChanges`, `envelopeFieldChanges` or `valueChanges` for an operation's or a webhook's parameter, an operation's response header, a field, an operation's list envelope field (`pagination.envelopeFields`, matched by name while both specs paginate) or an enum value. A model, enum, operation or webhook whose only change is the flag is still reported, with an empty nested list. Becoming or ceasing to be deprecated changes no contract — the node is still there with the same shape — so every one of these is additive, in either direction; it still counts as `modified` in the summary, and a breaking change on the same node (a removed field beside the model's flag, a changed response beside the operation's, a retyped payload beside the webhook's) keeps the change breaking. Each flip is also mirrored into `behaviorChanges` as a `deprecated-changed` entry naming the node (`operation`, `parameter`, `response-header`, `model`, `field`, `envelope-field`, `enum`, `enum-value`, `webhook` or `webhook-parameter`) and copying `oldDeprecated`/`newDeprecated` from the change, the way a parameter default change is, so a changelog can say which way it went without reading both specs. Parameters are compared in every location a node carries them — an operation's path, query, header and cookie parameters, a webhook's header, query and cookie parameters — and matched by location and name, since a path `id` and a query `id` may sit on one operation and a webhook's header and query parameters may share a name — a header's name compared case-insensitively, so a header deprecated and respelled `x-pet-token` in one step is still the `X-Pet-Token` it was, and its flip is reported; every `paramChanges` entry carries `paramLocation` to say which one it is about. A response header's flag is compared on every response entry that declares headers — the primary and every other 2xx/3xx entry, every error, the `default` and every range — with headers matched by name case-insensitively, and every `responseHeaderChanges` entry carries its `statusCode` or `fallback` to say which entry it is about (see Response Headers above).

## Enum

Expand Down
Loading
Loading