diff --git a/packages/downgrader/README.md b/packages/downgrader/README.md index c28a510..6c758b6 100644 --- a/packages/downgrader/README.md +++ b/packages/downgrader/README.md @@ -178,39 +178,39 @@ Schema Objects inside the document convert as in [Schema](#schema-downgradeschem Accepts the default OAS dialect, which adds `discriminator`, `xml`, `externalDocs`, and `example` to JSON Schema 2020-12. Every schema is read as 2020-12, whatever `$schema` or `jsonSchemaDialect` names. -| 3.1 | In 3.0 | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [`type`][js-type] with `"null"` | `nullable: true` beside the other type. `type: "null"` alone becomes `type: "string", nullable: true, enum: [null]`, since 3.0 allows `nullable` only beside `type`, and code generators drop a bare `enum: [null]`. | -| [`type`][js-type] with several types | `anyOf` with one branch per type, which takes `items` for `"array"`, and `properties`, `required`, `additionalProperties`, `minProperties`, and `maxProperties` for `"object"`. `"null"` gets its own branch, written as for `type: "null"` alone, since code generators ignore `nullable` inside an `anyOf` branch. | -| An [`anyOf`][js-any-of] of `{ type: "null" }` and one other branch, as Zod writes a nullable object, array, integer, enum, unknown, or `$ref`, Zod and Valibot a nullable nullish one with such a pair as the other branch, and Effect a nullish one with `{ type: "null" }` twice | That branch with `nullable: true` in place of the `anyOf` when it has a single `type`, since code generators read the pair as a union. A branch with a `$ref`, an `enum`, `allOf`, `anyOf`, `oneOf`, or `not` stays, since `nullable` would not let null through those, and so does one that holds a `type` where the schema around it holds one, or another keyword that schema holds with another value, or holds `properties` or `additionalProperties` where that schema holds the other, since `additionalProperties` reads the `properties` beside it. The pair becomes a `oneOf` when that branch has a `type` and no `nullable`, or is a `$ref` to such a schema, alone or with siblings such as the `description` Zod writes beside a described reference, since null then matches one branch only, and NSwag reads that as nullable but the `anyOf` as an empty class. A `$ref` to a schema whose `type` already holds `"null"`, as GitHub writes, takes the place of the `anyOf` when nothing else sits beside it, as 3.0 writes a nullable reference. A branch that accepts every value, such as `{}`, which Zod writes for a nullable unknown and Pydantic for `Optional[Any]`, removes the `anyOf`, since the pair then accepts every value too, and code generators read it as a union with a string or as a type they never define. Its annotations, such as the `description` Zod writes there for a described unknown, take its place, unless the schema around it has one of them with another value. A null branch whose other keywords repeat the schema around it, as ArkType writes the description of a described nullable value into every branch, or are its own `title`, `description`, `example`, or `x-` extensions, as Lithic and Mailgun document the null case, counts as `{ type: "null" }`. When the pair merges, the null branch's own keywords are dropped, since they describe only null. | -| A [`oneOf`][js-one-of] of `{ type: "null" }` and one other branch, as typia and Litestar write a nullable value | That branch with `nullable: true` in place of the `oneOf`, under the same conditions as the `anyOf` pair above but only with a single null branch and a branch without `nullable`, since null then matches one branch only. Otherwise the `oneOf` stays. | -| An [`anyOf`][js-any-of] of scalar types, or of them and `"array"`, as ArkType, Valibot and Pydantic write a union of them and Effect a number, and a [`type`][js-type] list of them, as Zod writes it and ASP.NET Core a number that may come as a string | A `oneOf` in place of the `anyOf` when each branch has a scalar or `"array"` `type` of its own and is not `nullable`, they do not name both `"integer"` and `"number"`, and no `enum` or `oneOf` sits beside them, since no value then matches two branches, with null in it once where Effect writes it twice for a nullish number. Such a `oneOf` with nothing beside it but annotations, as a nullable union of them becomes, joins the branches around it, and its annotations, such as the `description` Zod writes there for a described union, move to the schema around it, unless that schema or another such branch has one of them with another value. NSwag reads that `oneOf` as the first branch, and the OpenAPI Generator TypeScript client as a union, but the `anyOf` as an empty class. A schema a `$ref` points to keeps the `anyOf`, since NSwag gives a property a type it never defines when an `allOf` holds a `$ref` to a `oneOf`, as a `$ref` with siblings becomes. | -| [`const`][js-const] | `enum` with its one value, and the `type` of that value when it has none, since code generators drop or leave untyped a bare `enum`. `const: null` becomes the same schema as `type: "null"`. A union whose branches all become enums of one `type`, as OpenSearch writes a documented enum, gets that `type` beside it too, since NSwag otherwise reads it as an empty class or as a type it never defines. When those enums hold nothing else, as Zod, Valibot, TypeBox and GitHub write a union of literals, or only keywords the schema around them holds with the same value, as ArkType writes a described one, they become one `enum`, beside any null branch, since code generators read the union as a string or as a union of one-value types. Beside branches of other types, as Zod, ArkType and Valibot write a union of string literals and `number`, and utoipa the unit variants of a Rust enum, the enums of each type become one, and a union of scalars then becomes a `oneOf`. A `oneOf` whose branches share a value stays. | -| An [`enum`][js-enum] with no `type`, as ArkType writes a union of literals | The `type` its values share, when they share one, since code generators drop or leave untyped a bare `enum`, or read its integers as numbers. | -| Numeric [`exclusiveMinimum`][js-exclusive-minimum] and [`exclusiveMaximum`][js-exclusive-maximum] | `minimum` or `maximum` with a boolean `exclusiveMinimum` or `exclusiveMaximum`, unless `minimum` or `maximum` is stricter. | -| [`examples`][js-examples] | The first entry fills `example` when that is missing. | -| [`prefixItems`][js-prefix-items] | `items` matching any of the tuple's item schemas, and those of the items after them unless `items: false` or `maxItems` allows none, or `{}` when one of them accepts every value. That `anyOf` merges like the ones above, as for the key and value of a Zod `Map` entry. `items: false` becomes `maxItems`. | -| [`contentEncoding`][js-content-encoding] and [`contentMediaType`][js-content-media-type] | `format: "byte"` for `base64`, and `format: "binary"` for `binary` or a media type without an encoding or a `contentSchema`, which marks structured text. It replaces a `format` that only repeats the encoding, such as Zod's `format: "base64"`. Without a `type`, the schema gains `type: "string"`, unless it holds a `$ref`, `allOf`, `anyOf`, `oneOf`, `properties`, `items` or `prefixItems`, as a JSON body marked with its media type does. Then the keywords are removed. | -| An [`anyOf`][js-any-of] with a branch that holds only `contentMediaType`, as Zod writes for a file with several media types | Removed, since that branch matches every value. | -| An [`anyOf`][js-any-of] with branches that become equal, as oRPC 1.x writes a file with several media types, a string for each | A branch equal to the one before it is removed, as the `anyOf` then matches the same values, and a lone branch left takes the place of the `anyOf` when the schema around it holds only annotations that the branch lacks or holds with the same value, or nothing else beside a `$ref`, so a nullable one then merges as above. NSwag and oapi-codegen read the `anyOf` of equal binary strings as a generated class or a union, not as a file upload. Branches are equal when each keyword holds the same value, or the same object rather than a copy. A `oneOf` keeps them, since it rejects a value that two branches match. | -| A [`$ref`][js-ref] with siblings | `allOf: [{ $ref }]` beside the siblings, which 3.0 would ignore. A branch of a `oneOf` or `anyOf` beside a `discriminator` that stays, with only annotations beside its `$ref`, such as the `description` the Anthropic and ElevenLabs APIs write for each, becomes the bare `$ref` instead, since 3.0 maps a discriminator only to the `$ref`s among its branches, not to inline schemas, and oapi-codegen stops on the `allOf` there. So does a `$ref` with only annotations beside it to a schema whose `discriminator` stays, such as the `description` the OpenAI and Adyen APIs write beside a property holding a tagged union, since 3.0 reads an `allOf` holding that `$ref` as one of the schemas the discriminator picks among. openapi-typescript then leaves out its tag, and Hey API pins the tag to the name of the schema around it when the target has no `oneOf`, as for Adyen's base with a `mapping`. In both cases the annotations beside the `$ref` are dropped, so a `readOnly`, `writeOnly`, `default` or `deprecated` there is lost, as for the `readOnly` the Cryptography Provider API writes beside one. | -| [`$defs`][js-defs], and `definitions`, its draft-07 name | Removed. Each `$ref` into it is replaced by its converted target, where a reference back into a target being inlined becomes `{}`. | -| A [`discriminator`][3.0-schema-discriminator] over `$ref`s into `$defs`, as Pydantic and msgspec write a tagged union | Removed. A discriminator picks only among named components, not the targets that replace those `$ref`s, and its `mapping` into them would dangle, which validators that follow it, such as openapi-schema-validator, reject. | -| Boolean subschemas | `{}` for `true` and `{ not: {} }` for `false`, except in `additionalProperties`, which allows booleans. | -| [`patternProperties`][js-pattern-properties] | Removed. `additionalProperties` becomes `true`, as a schema or `false` there would reject the properties `patternProperties` allowed, and code generators read a missing one as closed. | -| [`$schema`][js-schema], [`$vocabulary`][js-vocabulary], [`$id`][js-id], [`$anchor`][js-anchor], [`$dynamicRef`, `$dynamicAnchor`][js-dynamic], [`$comment`][js-comment], and [`contentSchema`][js-content-schema] | Removed. | -| [`if`][js-if], [`then`][js-then], [`else`][js-else], [`dependentSchemas`][js-dependent-schemas], and [`dependentRequired`][js-dependent-required] | Removed. | -| [`contains`][js-contains], [`minContains`][js-min-contains], [`maxContains`][js-max-contains], and [`propertyNames`][js-property-names] | Removed. | -| [`propertyNames`][js-property-names] holding only an `enum` or `const`, or a `$ref` to one, as Zod and Valibot write record keys, with no `properties`, `patternProperties`, or `unevaluatedProperties` beside it | A property for each name, sharing the `additionalProperties` schema, and `additionalProperties: false`. A `$ref` into that schema is replaced by its target. A `title` or `description` beside the names is dropped. | -| [`unevaluatedProperties`][js-unevaluated-properties] | `additionalProperties`, when nothing beside it but `properties` evaluates properties. Otherwise removed. | -| [`unevaluatedItems`][js-unevaluated-items] | Removed. | -| An array without `items`, or an empty `required` | `items: {}`, which 3.0 requires, and no `required`, which 3.0 requires to be non-empty. | -| An empty [`enum`][js-enum], which 3.0 forbids | `allOf: [{ not: {} }]`, which also rejects every value. | -| Keywords that 3.0 does not define | `x-` extensions of the same name, since the 3.0 Schema Object allows no others. An existing extension of that name wins. | -| [`nullable`][3.0-schema-nullable], a 3.0 keyword | Kept beside a single `type`, where it means in 3.0 what its author meant, and the schema counts as having lost a restriction. Removed otherwise. | -| A boolean `exclusiveMinimum` or `exclusiveMaximum`, the 3.0 form, as NestJS writes in 3.1 | Kept beside a numeric `minimum` or `maximum`, where it means in 3.0 what its author meant. Removed otherwise. | -| [`not`][js-not] over a schema that lost a restriction above | Removed. Negating the looser schema would reject values the original accepts. A keyword that restricts nothing, such as `propertyNames: { type: "string" }`, or a tuple converted exactly, does not count. | -| [`oneOf`][js-one-of] with a branch that lost a restriction above | `anyOf`. Looser branches may overlap, and then match more than one. It stays a `oneOf` when no two branches can match the same value however loose they become: they have different types, other than `integer` and `number`, or one is an object that requires a property the other holds to other `const` or `enum` values, as OpenAI, Zod and oRPC write a tagged union, also in a member of an `allOf`, as OpenAI writes a resource. A `$ref` that recursion cuts to `{}` tells no branch apart. | +| 3.1 | In 3.0 | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`type`][js-type] with `"null"` | `nullable: true` beside the other type. `type: "null"` alone becomes `type: "string", nullable: true, enum: [null]`, since 3.0 allows `nullable` only beside `type`, and code generators drop a bare `enum: [null]`. | +| [`type`][js-type] with several types | `anyOf` with one branch per type, which takes `items` for `"array"`, and `properties`, `required`, `additionalProperties`, `minProperties`, and `maxProperties` for `"object"`. `"null"` gets its own branch, written as for `type: "null"` alone, since code generators ignore `nullable` inside an `anyOf` branch. | +| An [`anyOf`][js-any-of] of `{ type: "null" }` and one other branch, as Zod writes a nullable object, array, integer, enum, unknown, or `$ref`, Zod and Valibot a nullable nullish one with such a pair as the other branch, and Effect a nullish one with `{ type: "null" }` twice | That branch with `nullable: true` in place of the `anyOf` when it has a single `type`, since code generators read the pair as a union. A branch with a `$ref`, an `enum`, `allOf`, `anyOf`, `oneOf`, or `not` stays, since `nullable` would not let null through those, and so does one that holds a `type` where the schema around it holds one, or another keyword that schema holds with another value, or holds `properties` or `additionalProperties` where that schema holds the other, since `additionalProperties` reads the `properties` beside it. The pair becomes a `oneOf` when that branch has a `type` and no `nullable`, or is a `$ref` to such a schema, alone or with siblings such as the `description` Zod writes beside a described reference, or is an `allOf` with such a member in any place, as Zod writes a nullable intersection, since null then matches one branch only, and NSwag reads that as nullable but the `anyOf` as an empty class. A `$ref` to a schema whose `type` already holds `"null"`, as GitHub writes, takes the place of the `anyOf` when nothing else sits beside it, as 3.0 writes a nullable reference. A branch that accepts every value, such as `{}`, which Zod writes for a nullable unknown and Pydantic for `Optional[Any]`, removes the `anyOf`, since the pair then accepts every value too, and code generators read it as a union with a string or as a type they never define. Its annotations, such as the `description` Zod writes there for a described unknown, take its place, unless the schema around it has one of them with another value. A null branch whose other keywords repeat the schema around it, as ArkType writes the description of a described nullable value into every branch, or are its own `title`, `description`, `example`, or `x-` extensions, as Lithic and Mailgun document the null case, counts as `{ type: "null" }`. When the pair merges, the null branch's own keywords are dropped, since they describe only null. | +| A [`oneOf`][js-one-of] of `{ type: "null" }` and one other branch, as typia and Litestar write a nullable value | That branch with `nullable: true` in place of the `oneOf`, under the same conditions as the `anyOf` pair above but only with a single null branch and a branch without `nullable`, since null then matches one branch only. Otherwise the `oneOf` stays. | +| An [`anyOf`][js-any-of] of scalar types, or of them and `"array"`, as ArkType, Valibot and Pydantic write a union of them and Effect a number, and a [`type`][js-type] list of them, as Zod writes it and ASP.NET Core a number that may come as a string | A `oneOf` in place of the `anyOf` when each branch has a scalar or `"array"` `type` of its own and is not `nullable`, they do not name both `"integer"` and `"number"`, and no `enum` or `oneOf` sits beside them, since no value then matches two branches, with null in it once where Effect writes it twice for a nullish number. Such a `oneOf` with nothing beside it but annotations, as a nullable union of them becomes, joins the branches around it, and its annotations, such as the `description` Zod writes there for a described union, move to the schema around it, unless that schema or another such branch has one of them with another value. NSwag reads that `oneOf` as the first branch, and the OpenAPI Generator TypeScript client as a union, but the `anyOf` as an empty class. A schema a `$ref` points to keeps the `anyOf`, since NSwag gives a property a type it never defines when an `allOf` holds a `$ref` to a `oneOf`, as a `$ref` with siblings becomes. | +| [`const`][js-const] | `enum` with its one value, and the `type` of that value when it has none, since code generators drop or leave untyped a bare `enum`. `const: null` becomes the same schema as `type: "null"`. A union whose branches all become enums of one `type`, as OpenSearch writes a documented enum, gets that `type` beside it too, since NSwag otherwise reads it as an empty class or as a type it never defines. When those enums hold nothing else, as Zod, Valibot, TypeBox and GitHub write a union of literals, or only keywords the schema around them holds with the same value, as ArkType writes a described one, they become one `enum`, beside any null branch, since code generators read the union as a string or as a union of one-value types. Beside branches of other types, as Zod, ArkType and Valibot write a union of string literals and `number`, and utoipa the unit variants of a Rust enum, the enums of each type become one, and a union of scalars then becomes a `oneOf`. A `oneOf` whose branches share a value stays. | +| An [`enum`][js-enum] with no `type`, as ArkType writes a union of literals | The `type` its values share, when they share one, since code generators drop or leave untyped a bare `enum`, or read its integers as numbers. | +| Numeric [`exclusiveMinimum`][js-exclusive-minimum] and [`exclusiveMaximum`][js-exclusive-maximum] | `minimum` or `maximum` with a boolean `exclusiveMinimum` or `exclusiveMaximum`, unless `minimum` or `maximum` is stricter. | +| [`examples`][js-examples] | The first entry fills `example` when that is missing. | +| [`prefixItems`][js-prefix-items] | `items` matching any of the tuple's item schemas, and those of the items after them unless `items: false` or `maxItems` allows none, or `{}` when one of them accepts every value. That `anyOf` merges like the ones above, as for the key and value of a Zod `Map` entry. `items: false` becomes `maxItems`. | +| [`contentEncoding`][js-content-encoding] and [`contentMediaType`][js-content-media-type] | `format: "byte"` for `base64`, and `format: "binary"` for `binary` or a media type without an encoding or a `contentSchema`, which marks structured text. It replaces a `format` that only repeats the encoding, such as Zod's `format: "base64"`. Without a `type`, the schema gains `type: "string"`, unless it holds a `$ref`, `allOf`, `anyOf`, `oneOf`, `properties`, `items` or `prefixItems`, as a JSON body marked with its media type does. Then the keywords are removed. | +| An [`anyOf`][js-any-of] with a branch that holds only `contentMediaType`, as Zod writes for a file with several media types | Removed, since that branch matches every value. | +| An [`anyOf`][js-any-of] with branches that become equal, as oRPC 1.x writes a file with several media types, a string for each | A branch equal to the one before it is removed, as the `anyOf` then matches the same values, and a lone branch left takes the place of the `anyOf` when the schema around it holds only annotations that the branch lacks or holds with the same value, or nothing else beside a `$ref`, so a nullable one then merges as above. NSwag and oapi-codegen read the `anyOf` of equal binary strings as a generated class or a union, not as a file upload. Branches are equal when each keyword holds the same value, or the same object rather than a copy. A `oneOf` keeps them, since it rejects a value that two branches match. | +| A [`$ref`][js-ref] with siblings | `allOf: [{ $ref }]` beside the siblings, which 3.0 would ignore. A branch of a `oneOf` or `anyOf` beside a `discriminator` that stays, with only annotations beside its `$ref`, such as the `description` the Anthropic and ElevenLabs APIs write for each, becomes the bare `$ref` instead, since 3.0 maps a discriminator only to the `$ref`s among its branches, not to inline schemas, and oapi-codegen stops on the `allOf` there. So does a `$ref` with only annotations beside it to a schema whose `discriminator` stays, such as the `description` the OpenAI and Adyen APIs write beside a property holding a tagged union, since 3.0 reads an `allOf` holding that `$ref` as one of the schemas the discriminator picks among. openapi-typescript then leaves out its tag, and Hey API pins the tag to the name of the schema around it when the target has no `oneOf`, as for Adyen's base with a `mapping`. In both cases the annotations beside the `$ref` are dropped, so a `readOnly`, `writeOnly`, `default` or `deprecated` there is lost, as for the `readOnly` the Cryptography Provider API writes beside one. | +| [`$defs`][js-defs], and `definitions`, its draft-07 name | Removed. Each `$ref` into it is replaced by its converted target, where a reference back into a target being inlined becomes `{}`. | +| A [`discriminator`][3.0-schema-discriminator] over `$ref`s into `$defs`, as Pydantic and msgspec write a tagged union | Removed. A discriminator picks only among named components, not the targets that replace those `$ref`s, and its `mapping` into them would dangle, which validators that follow it, such as openapi-schema-validator, reject. | +| Boolean subschemas | `{}` for `true` and `{ not: {} }` for `false`, except in `additionalProperties`, which allows booleans. | +| [`patternProperties`][js-pattern-properties] | Removed. `additionalProperties` becomes `true`, as a schema or `false` there would reject the properties `patternProperties` allowed, and code generators read a missing one as closed. | +| [`$schema`][js-schema], [`$vocabulary`][js-vocabulary], [`$id`][js-id], [`$anchor`][js-anchor], [`$dynamicRef`, `$dynamicAnchor`][js-dynamic], [`$comment`][js-comment], and [`contentSchema`][js-content-schema] | Removed. | +| [`if`][js-if], [`then`][js-then], [`else`][js-else], [`dependentSchemas`][js-dependent-schemas], and [`dependentRequired`][js-dependent-required] | Removed. | +| [`contains`][js-contains], [`minContains`][js-min-contains], [`maxContains`][js-max-contains], and [`propertyNames`][js-property-names] | Removed. | +| [`propertyNames`][js-property-names] holding only an `enum` or `const`, or a `$ref` to one, as Zod and Valibot write record keys, with no `properties`, `patternProperties`, or `unevaluatedProperties` beside it | A property for each name, sharing the `additionalProperties` schema, and `additionalProperties: false`. A `$ref` into that schema is replaced by its target. A `title` or `description` beside the names is dropped. | +| [`unevaluatedProperties`][js-unevaluated-properties] | `additionalProperties`, when nothing beside it but `properties` evaluates properties. Otherwise removed. | +| [`unevaluatedItems`][js-unevaluated-items] | Removed. | +| An array without `items`, or an empty `required` | `items: {}`, which 3.0 requires, and no `required`, which 3.0 requires to be non-empty. | +| An empty [`enum`][js-enum], which 3.0 forbids | `allOf: [{ not: {} }]`, which also rejects every value. | +| Keywords that 3.0 does not define | `x-` extensions of the same name, since the 3.0 Schema Object allows no others. An existing extension of that name wins. | +| [`nullable`][3.0-schema-nullable], a 3.0 keyword | Kept beside a single `type`, where it means in 3.0 what its author meant, and the schema counts as having lost a restriction. Removed otherwise. | +| A boolean `exclusiveMinimum` or `exclusiveMaximum`, the 3.0 form, as NestJS writes in 3.1 | Kept beside a numeric `minimum` or `maximum`, where it means in 3.0 what its author meant. Removed otherwise. | +| [`not`][js-not] over a schema that lost a restriction above | Removed. Negating the looser schema would reject values the original accepts. A keyword that restricts nothing, such as `propertyNames: { type: "string" }`, or a tuple converted exactly, does not count. | +| [`oneOf`][js-one-of] with a branch that lost a restriction above | `anyOf`. Looser branches may overlap, and then match more than one. It stays a `oneOf` when no two branches can match the same value however loose they become: they have different types, other than `integer` and `number`, or one is an object that requires a property the other holds to other `const` or `enum` values, as OpenAI, Zod and oRPC write a tagged union, also in a member of an `allOf`, as OpenAI writes a resource. A `$ref` that recursion cuts to `{}` tells no branch apart. | [js-type]: https://json-schema.org/draft/2020-12/json-schema-validation#name-type [js-const]: https://json-schema.org/draft/2020-12/json-schema-validation#name-const diff --git a/packages/downgrader/src/v3.1-to-v3.0.ts b/packages/downgrader/src/v3.1-to-v3.0.ts index 27cd9ba..d8cdd57 100644 --- a/packages/downgrader/src/v3.1-to-v3.0.ts +++ b/packages/downgrader/src/v3.1-to-v3.0.ts @@ -911,13 +911,19 @@ function mergeNullable(out: Record, root: unknown, key: 'anyOf' delete out[key] Object.assign(out, other, { nullable: true }) } else if (key === 'anyOf' && out.oneOf === undefined) { - // A `$ref` kept as written rejects null when its target does, and so does - // the `allOf` that holds a `$ref` with siblings, as Zod writes the - // description of a described reference beside it. + // A `$ref` kept as written rejects null when its target does, and an + // `allOf` when any of its members does, such as the `$ref` with siblings + // that Zod writes for a described reference, or either side of an + // intersection. const ref = getRef(other) const target = ref === undefined ? other : find(root, ref) - const held = Array.isArray(other.allOf) ? getRef(other.allOf[0]) : undefined - if (rejectsNull(target) || (held !== undefined && rejectsNull(find(root, held)))) { + const held = + Array.isArray(other.allOf) && + other.allOf.some((member) => { + const memberRef = getRef(member) + return rejectsNull(memberRef === undefined ? member : find(root, memberRef)) + }) + if (rejectsNull(target) || held) { // Null once, since `oneOf` rejects a value that matches two branches. const nullBranch = branches.find((branch) => isNullBranch(branch, out)) out.oneOf = branches[0] === other ? [other, nullBranch] : [nullBranch, other] diff --git a/packages/downgrader/tests/v3.1-to-v3.0.test.ts b/packages/downgrader/tests/v3.1-to-v3.0.test.ts index 1a0ab2d..e10f573 100644 --- a/packages/downgrader/tests/v3.1-to-v3.0.test.ts +++ b/packages/downgrader/tests/v3.1-to-v3.0.test.ts @@ -1072,6 +1072,38 @@ describe('downgradeSchemaV31ToV30', () => { expect(described({ type: ['object', 'null'] })).toEqual({ anyOf: [wrapped, onlyNull] }) }) + it('makes an anyOf of an allOf and null a oneOf when any member rejects null', () => { + const onlyNull = { type: 'string', nullable: true, enum: [null] } + const base = { type: 'object', properties: { b: { type: 'string' } } } as const + const open = { properties: { b: { type: 'string' } } } as const + const ref = { $ref: '#/components/schemas/Pet' } + // oRPC writes Zod's `z.intersection(B, Pet).nullable()` with the `$ref` second. + const owner = (first: OpenAPIV3_1.SchemaObject, target: OpenAPIV3_1.SchemaObject) => + convert({ + components: { + schemas: { + Pet: target, + Owner: { anyOf: [{ allOf: [first, ref] }, { type: 'null' }] }, + }, + }, + }).components?.schemas?.Owner + expect(owner(base, { type: 'object' })).toEqual({ oneOf: [{ allOf: [base, ref] }, onlyNull] }) + // One member that rejects null is enough, in either place. + expect(owner(base, { type: ['object', 'null'] })).toEqual({ + oneOf: [{ allOf: [base, ref] }, onlyNull], + }) + expect(owner(open, { type: 'object' })).toEqual({ oneOf: [{ allOf: [open, ref] }, onlyNull] }) + // Null can pass every member, so it can match both branches. + expect(owner(open, { type: ['object', 'null'] })).toEqual({ + anyOf: [{ allOf: [open, ref] }, onlyNull], + }) + // An intersection of two inline objects. + const other = { type: 'object', properties: { c: { type: 'number' } } } as const + expect( + downgradeSchemaV31ToV30({ anyOf: [{ allOf: [base, other] }, { type: 'null' }] }), + ).toEqual({ oneOf: [{ allOf: [base, other] }, onlyNull] }) + }) + it('keeps only the $ref of an anyOf with null when the target admits null, as GitHub writes it', () => { const ref = { $ref: '#/components/schemas/Pet' } const owner = (target: OpenAPIV3_1.SchemaObject, extra: object = {}) =>