-
Notifications
You must be signed in to change notification settings - Fork 2
Schema Changes
Adil Bektursunov edited this page Mar 18, 2026
·
14 revisions
Scope Request: When a schema is used in contexts where the client sends JSON data to the server:
- RequestBody schemas
- Parameter schemas
Scope Response: When a schema is used in contexts where the client receives JSON data from the server:
- ResponseBody schemas
- ResponseHeader schemas
| # | Path | ChangeID | Comment | Example | ExpectedResultScopeRequest | ExpectedResultScopeResponse | Version Combination | Source | Status | Link |
|---|---|---|---|---|---|---|---|---|---|---|
| 1 | allOf | add-all-of | before after | add-all-of | ||||||
| 2 | allOf. [*] | add-all-of-option | before after | non-breaking | non-breaking | add-all-of-option | ||||
| 3 | anyOf | add-any-of | before after | non-breaking | breaking | Approved (Response Scope) | add-any-of | |||
| 4 | anyOf. [*] | add-any-of-option | before after | non-breaking | breaking | Approved (Response Scope) | add-any-of-option | |||
| 5 | add-attribute-with-default-value-for-xml | before after | [not supported] | [not supported] | add-attribute-with-default-value-for-xml | |||||
| 6 | anyOf.discriminator.[*] | add-discriminator-for-any-of | before after | [not applicable] | add-discriminator-for-any-of | |||||
| 7 | oneOf.discriminator.[*] | add-discriminator-for-one-of | before after | [not applicable] | add-discriminator-for-one-of | |||||
| 8 | enum | add-enum | before after | breaking | non-breaking | Approved | add-enum | |||
| 9 | enum. value | add-enum-value | before after | non-breaking | requires attention | Approved | add-enum-value | |||
| 10 | format. value | add-format-for-number-property | for number type | before after | breaking | non-breaking | Approved | add-format-for-number-property | ||
| 11 | format. value | add-format-for-string-property | for string type | before after | breaking | non-breaking | Approved | add-format-for-string-property | ||
| 12 | maxItems. value | add-max-items-for-array-property | for array type | before after | breaking | non-breaking | add-max-items-for-array-property | |||
| 13 | maxLength. value | add-max-length-for-string-property | for string type | before after | breaking | non-breaking | add-max-length-for-string-property | |||
| 14 | maxProperties. value | add-max-properties-for-object-property | for object type | before after | breaking | non-breaking | add-max-properties-for-object-property | |||
| 15 | maximum. value | add-maximum-for-number-property | for number type | before after | breaking | non-breaking | add-maximum-for-number-property | |||
| 16 | minItems. value | add-min-items-for-array-property | for array type | before after | breaking | non-breaking | add-min-items-for-array-property | |||
| 17 | minLength. value | add-min-length-for-string-property | for string type | before after | breaking | non-breaking | add-min-length-for-string-property | |||
| 18 | minProperties. value | add-min-properties-for-object-property | for object type | before after | breaking | non-breaking | add-min-properties-for-object-property | |||
| 19 | (for array type) minItems. value | add-minItems-with-default-value-for-array-property | before after | [not applicable] | add-minItems-with-default-value-for-array-property | |||||
| 20 | (for object type) minProperties. value | add-minProperties-with-default-value-for-object-property | before after | [not applicable] | add-minProperties-with-default-value-for-object-property | |||||
| 21 | minimum. value | add-minimum-for-number-property | for number type | before after | breaking | non-breaking | add-minimum-for-number-property | |||
| 22 | multiplyOf. value | add-multiple-of-for-number-property | for number type | before after | breaking | non-breaking | add-multiple-of-for-number-property | |||
| 23 | properties. value | add-new-property-compliance | (compliance with additional properties ) | before after | non-breaking | non-breaking | Approved (Response Scope) | add-new-property-compliance | ||
| 24 | additionalProperties.type. value | add-non-boolean-additional-properties | i.e. define dictionary with value of specific type | before after | breaking | requires attention | Approved (Response Scope) | add-non-boolean-additional-properties | ||
| 25 | add-null-to-union-type | before after | non-breaking | breaking | [3.1.0, 3.1.0] | add-null-to-union-type | ||||
| 26 | oneOf | add-one-of | before after | N non-breaking | breaking | Approved (Response Scope) | add-one-of | |||
| 27 | oneOf. [*] | add-one-of-option | before after | non-breaking | breaking | Approved (Response Scope) | add-one-of-option | |||
| 28 | pattern. value | add-pattern-for-string-property | for string type | before after | breaking | non-breaking | add-pattern-for-string-property | |||
| 29 | required. value | add-required-property | for object type | before after | breaking | non-breaking | Approved (Response Scope) | add-required-property | ||
| 30 | required. value | add-required-property-with-default | for object type | before after | breaking | non-breaking | Approved | add-required-property-with-default | ||
| 31 | title. value | add-schema-title | before after | annotation | annotation | add-schema-title | ||||
| 32 | add-sibling-description-for-ref | before after | annotation | annotation | [3.1.0, 3.1.0], [3.0.0, 3.1.0] | add-sibling-description-for-ref | ||||
| 33 | add-union-type | before after | non-breaking | breaking | [3.0.0, 3.1.0], [3.1.0, 3.1.0] | add-union-type | ||||
| 34 | (for array type) uniqueItems. value | add-uniqueItems-with-default-value-for-array-property | before after | [not applicable] | add-uniqueItems-with-default-value-for-array-property | |||||
| 35 | add-xml-name-replacement-for-property | (default xml name the same as prop name) | before after | [not supported] breaking ? | requires attention | Approved (Response Scope) | add-xml-name-replacement-for-property | |||
| 36 | add-xml-name-replacement-for-schema | add xml name replacement for schema components.schema is necessary to define xml element name (is it possible to specify xml element name inline?) default xml name the same as schema name | before after | [not supported] breaking ? | requires attention | Approved (Response Scope) | add-xml-name-replacement-for-schema | |||
| 37 | add-xml-prefix-and-namespace-for-schema | (prefix and namespace in once case as both must be specified) | before after | [not supported] 2 breaking ? | breaking ? | add-xml-prefix-and-namespace-for-schema | ||||
| 38 | add-xml-wrapped-for-array-property | before after | [not supported] breaking ? | breaking [not supported] | add-xml-wrapped-for-array-property | |||||
| 39 | add-xml-wrapped-with-default-value-for-array-property | before after | [not supported] | [not supported] | add-xml-wrapped-with-default-value-for-array-property | |||||
| 40 | uniqueItems. value | allow-non-unique-items-for-array-property | for array type | before after | non-breaking | breaking | Approved (Response Scope) | allow-non-unique-items-for-array-property | ||
| 41 | change-referenced-enum-when-sibling-exists-for-ref | before after | non-breaking | risky | [3.1.0, 3.1.0] | change-referenced-enum-when-sibling-exists-for-ref | ||||
| 42 | change-sibling-enum-for-ref | before after | annotation | annotation | [3.1.0, 3.1.0] | change-sibling-enum-for-ref | ||||
| 43 | maxItems. value | decrease-max-items-for-array-property | for array type | before after | breaking | non-breaking | decrease-max-items-for-array-property | |||
| 44 | maxLength. value | decrease-max-length-for-string-property | for string type | before after | breaking | non-breaking | decrease-max-length-for-string-property | |||
| 45 | maxProperties. value | decrease-max-properties-for-object-property | for object type | before after | breaking | non-breaking | decrease-max-properties-for-object-property | |||
| 46 | maximum. value | decrease-maximum-for-number-property | for number type | before after | breaking | non-breaking | decrease-maximum-for-number-property | |||
| 47 | minItems. value | decrease-min-items-for-array-property | for array type | before after | non-breaking | breaking | Approved (Response Scope) | decrease-min-items-for-array-property | ||
| 48 | minLength. value | decrease-min-length-for-string-property | for string type | before after | non-breaking | requires attention | Approved (Response Scope) | decrease-min-length-for-string-property | ||
| 49 | minProperties. value | decrease-min-properties-for-object-property | for object type | before after | non-breaking | breaking | Approved (Response Scope) | decrease-min-properties-for-object-property | ||
| 50 | minimum. value | decrease-minimum-for-number-property | for number type | before after | non-breaking | requires attention | Approved (Response Scope) | decrease-minimum-for-number-property | ||
| 51 | minimum. value | decrease-minimum-for-required-number-property | for number type (required property) | before after | non-breaking | breaking | decrease-minimum-for-required-number-property | |||
| 52 | maxItems. value | increase-max-items-for-array-property | for array type | before after | non-breaking | requires attention | Approved (Response Scope) | increase-max-items-for-array-property | ||
| 53 | maxLength. value | increase-max-length-for-string-property | for string type | before after | non-breaking | requires attention | Approved (Response Scope) | increase-max-length-for-string-property | ||
| 54 | maxProperties. value | increase-max-properties-for-object-property | for object type | before after | non-breaking | requires attention | Approved (Response Scope) | increase-max-properties-for-object-property | ||
| 55 | maximum. value | increase-maximum-for-number-property | for number type | before after | non-breaking | requires attention | Approved (Response Scope) | increase-maximum-for-number-property | ||
| 56 | minItems. value | increase-min-items-for-array-property | for array type | before after | breaking | non-breaking | increase-min-items-for-array-property | |||
| 57 | minLength. value | increase-min-length-for-string-property | for string type | before after | breaking | non-breaking | increase-min-length-for-string-property | |||
| 58 | minProperties. value | increase-min-properties-for-object-property | for object type | before after | breaking | non-breaking | increase-min-properties-for-object-property | |||
| 59 | minimum. value | increase-minimum-for-number-property | for number type | before after | breaking | non-breaking | increase-minimum-for-number-property | |||
| 60 | exclusiveMaximum. value | mark-maximum-value-as-exclusive-for-number-property | for number type | before after | breaking + non-breaking | non-breaking | mark-maximum-value-as-exclusive-for-number-property | |||
| 61 | exclusiveMaximum. value | mark-maximum-value-as-inclusive-for-number-property | for number type | before after | non-breaking | requires attention | Approved (Response Scope) | mark-maximum-value-as-inclusive-for-number-property | ||
| 62 | exclusiveMinimum. value | mark-minimum-value-as-exclusive-for-number-property | for number type | before after | breaking + non-breaking | non-breaking | mark-minimum-value-as-exclusive-for-number-property | |||
| 63 | minimum. value | mark-minimum-value-as-inclusive-for-number-property | for number type | before after | non-breaking | requires attention | Approved (Response Scope) | mark-minimum-value-as-inclusive-for-number-property | ||
| 64 | readOnly. value | mark-object-property-as-not-read-only | for object type | before after | non-breaking | non-breaking | mark-object-property-as-not-read-only | |||
| 65 | writeOnly. value | mark-object-property-as-not-write-only | before after | non-breaking | non-breaking | mark-object-property-as-not-write-only | ||||
| 66 | readOnly. value | mark-object-property-as-read-only | for object type | before after | breaking | non-breaking | mark-object-property-as-read-only | |||
| 67 | writeOnly. value | mark-object-property-as-write-only | writeOnly properties may be sent only in requests | before after | non-breaking | non-breaking | mark-object-property-as-write-only | |||
| 68 | mark-property-as-xml-attribute | before after | [not supported] breaking | requires attention | Approved (Response Scope) | mark-property-as-xml-attribute | ||||
| 69 | mark-property-as-xml-element | before after | [not supported] breaking ? | non-breaking | Approved (Response Scope) | mark-property-as-xml-element | ||||
| 70 | nullable. value | mark-schema-value-as-non-nullable | before after | breaking | non-breaking | [3.0.0, 3.0.0] | mark-schema-value-as-non-nullable | |||
| 71 | nullable. value | mark-schema-value-as-nullable | before after | non-breaking | breaking | [3.0.0, 3.0.0] | Approved (Request Scope) | mark-schema-value-as-nullable | ||
| 72 | nullable-equivalent-to-null | before after | annotation | annotation | [3.0.0, 3.1.0] | nullable-equivalent-to-null | ||||
| 73 | uniqueItems. value | prohibit-non-unique-items-for-array-property | for array type | before after | breaking | non-breaking | prohibit-non-unique-items-for-array-property | |||
| 74 | additionalProperties.type. value | remove-additional-properties | before after | breaking | breaking | Approved (Response Scope) | remove-additional-properties | |||
| 75 | allOf. [*] | remove-all-of | remove allOf + one of the object inside allOf | before after | non-breaking | non-breaking | remove-all-of | |||
| 76 | allOf. [*] | remove-all-of-option | before after | non-breaking | non-breaking | remove-all-of-option | ||||
| 77 | anyOf. [*] | remove-any-of | remove anyOf + one of the object inside anyOf | before after | breaking | non-breaking | remove-any-of | |||
| 78 | anyOf. [*] | remove-any-of-option | before after | breaking | non-breaking | remove-any-of-option | ||||
| 79 | remove-attribute-with-default-value-for-xml | before after | [not supported] | [not supported] | remove-attribute-with-default-value-for-xml | |||||
| 80 | remove-discriminator-for-any-of | before after | [not applicable] | remove-discriminator-for-any-of | ||||||
| 81 | remove-discriminator-for-one-of | before after | [not applicable] | remove-discriminator-for-one-of | ||||||
| 82 | enum | remove-enum | before after | non-breaking | breaking | Approved | remove-enum | |||
| 83 | enum. value | remove-enum-value | before after | breaking | requires attention | Approved | remove-enum-value | |||
| 84 | format. value | remove-format-for-number-property | for number type | before after | non-breaking | requires attention | Approved | remove-format-for-number-property | ||
| 85 | format. value | remove-format-for-string-property | for string type | before after | non-breaking | requires attention | Approved | remove-format-for-string-property | ||
| 86 | maxItems. value | remove-max-items-for-array-property | for array type | before after | non-breaking | requires attention | Approved (Response Scope) | remove-max-items-for-array-property | ||
| 87 | maxLength. value | remove-max-length-for-string-property | for string type | before after | non-breaking | requires attention | Approved (Response Scope) | remove-max-length-for-string-property | ||
| 88 | maxProperties. value | remove-max-properties-for-object-property | for object type | before after | non-breaking | requires attention | Approved (Response Scope) | remove-max-properties-for-object-property | ||
| 89 | maximum. value | remove-maximum-for-number-property | for number type | before after | non-breaking | requires attention | Approved (Response Scope) | remove-maximum-for-number-property | ||
| 90 | minItems. value | remove-min-items-for-array-property | for array type | before after | non-breaking | breaking | Approved (Response Scope) | remove-min-items-for-array-property | ||
| 91 | minLength. value | remove-min-length-for-string-property | for string type | before after | non-breaking | breaking | Approved (Response Scope) | remove-min-length-for-string-property | ||
| 92 | minProperties. value | remove-min-properties-for-object-property | for object type | before after | non-breaking | breaking | Approved (Response Scope) | remove-min-properties-for-object-property | ||
| 93 | remove-minItems-with-default-value-for-array-property | before after | [not applicable] | remove-minItems-with-default-value-for-array-property | ||||||
| 94 | remove-minProperties-with-default-value-for-object-property | before after | [not applicable] | remove-minProperties-with-default-value-for-object-property | ||||||
| 95 | minimum. value | remove-minimum-for-number-property | for number type | before after | non-breaking | requires attention | Approved (Response Scope) | remove-minimum-for-number-property | ||
| 96 | minimum. value | remove-minimum-for-required-number-property | for number type (required property) | before after | non-breaking | breaking | remove-minimum-for-required-number-property | |||
| 97 | multiplyOf. value | remove-multiple-of-for-number-property | for number type | before after | non-breaking | breaking ? | remove-multiple-of-for-number-property | |||
| 98 | remove-null-from-union-type | before after | breaking | non-breaking | [3.1.0, 3.1.0] | remove-null-from-union-type | ||||
| 99 | oneOf | remove-one-of | remove oneOf + one of the object inside oneOf | before after | N breaking | N non-breaking | remove-one-of | |||
| 100 | oneOf. [*] | remove-one-of-option | before after | breaking | non-breaking | remove-one-of-option | ||||
| 101 | pattern. value | remove-pattern-for-string-property | for string type | before after | non-breaking | breaking | Approved (Response Scope) | remove-pattern-for-string-property | ||
| 102 | properties. value | remove-property-compliance | before after | non-breaking | non-breaking | Approved | remove-property-compliance | |||
| 103 | required. value | remove-required-status-from-property | for object type | before after | non-breaking | breaking | Approved (Response Scope) | remove-required-status-from-property | ||
| 104 | required. value, properties. value | remove-required-property-compliance | required property + property removal combined | before after | non-breaking | breaking | remove-required-property-compliance | |||
| 105 | title. value | remove-schema-title | before after | annotation | annotation | remove-schema-title | ||||
| 106 | remove-sibling-maxLength-for-ref | before after | non-breaking | requires attention | [3.1.0, 3.1.0], [3.1.0, 3.0.0] | remove-sibling-maxLength-for-ref | ||||
| 107 | remove-union-type | before after | breaking | non-breaking | [3.1.0, 3.1.0], [3.1.0, 3.0.0] | remove-union-type | ||||
| 108 | remove-uniqueItems-with-default-value-for-array-property | before after | [not applicable] | remove-uniqueItems-with-default-value-for-array-property | ||||||
| 109 | remove-xml-name-replacement-for-property | before after | [not supported] breaking ? | requires attention | Approved (Response Scope) | remove-xml-name-replacement-for-property | ||||
| 110 | remove-xml-name-replacement-for-schema | (components.schema is necessary to define xml element name) | before after | [not supported] breaking ? | breaking | Approved (Response Scope) | remove-xml-name-replacement-for-schema | |||
| 111 | remove-xml-prefix-and-namespace-for-schema | before after | [not supported] 2 breaking ? | breaking ? | remove-xml-prefix-and-namespace-for-schema | |||||
| 112 | remove-xml-wrapped-for-array-property | before after | [not supported] breaking ? | breaking [not supported] | remove-xml-wrapped-for-array-property | |||||
| 113 | remove-xml-wrapped-with-default-value-for-array-property | before after | [not supported] | [not supported] | remove-xml-wrapped-with-default-value-for-array-property | |||||
| 114 | reorder-types-in-union-type | before after | annotation | annotation | [3.1.0, 3.1.0] | reorder-types-in-union-type | ||||
| 115 | union-type-equivalent-to-any-of | before after | annotation | annotation | [3.0.0, 3.1.0], [3.1.0, 3.1.0] | union-type-equivalent-to-any-of | ||||
| 116 | additionalProperties. value | update-definition-of-free-form-object | for object type | before after | non-breaking ? | non-breaking no changes (effectively nothing was changed) | update-definition-of-free-form-object | |||
| 117 | update-discriminator-for-any-of | before after | [not applicable] | update-discriminator-for-any-of | ||||||
| 118 | update-discriminator-for-one-of | before after | [not applicable] | update-discriminator-for-one-of | ||||||
| 119 | enum. value | update-enum-value | before after | 1 breaking (for removed enum) and 1 non-breaking (for added enum) ? | 1 requires attention (for added enum value) and 1 non-breaking (for deleted enum value) | Approved | update-enum-value | |||
| 120 | format. value | update-format-for-number-property | for number type | before after | breaking | requires attention | Approved | update-format-for-number-property | ||
| 121 | format. value | update-format-for-string-property | for string type | before after | breaking | requires attention | Approved | update-format-for-string-property | ||
| 122 | multiplyOf. value | update-multiple-of-for-number-property | for number type | before after | breaking | requires attention | Approved (Response Scope) | update-multiple-of-for-number-property | ||
| 123 | pattern. value | update-pattern-for-string-property | for string type | before after | breaking | breaking | Approved (Response Scope) | update-pattern-for-string-property | ||
| 124 | required. value | update-required-property | for object type | before after | 2 changes: breaking for adding required property for prop2 non-breaking for removing required property for prop1 | 2 changes: breaking for removing required property for prop1 non-breaking for adding required property for prop2 | Approved (Response Scope) | update-required-property | ||
| 125 | title. value | update-schema-title | before after | annotation | annotation | update-schema-title | ||||
| 126 | type. value | update-schema-type | before after | breaking | breaking | Approved | update-schema-type | |||
| 127 | type. value | update-schema-type-from-any-type-to-specific-type | before after | [not supported] breaking | [not supported] non-breaking | update-schema-type-from-any-type-to-specific-type | ||||
| 128 | type. value | update-schema-type-from-nothing-to-specific-type | before after | [not supported] non-breaking | [not applicable] | update-schema-type-from-nothing-to-specific-type | ||||
| 129 | type. value | update-schema-type-from-specific-type-to-any-type | before after | non-breaking | breaking | Approved (Request Scope) | update-schema-type-from-specific-type-to-any-type | |||
| 130 | type. value | update-schema-type-from-specific-type-to-nothing | before after | breaking | [not applicable] | Approved (Request Scope) | update-schema-type-from-specific-type-to-nothing | |||
| 131 | type. value | update-schema-type-to-an-equivalent-value | before after | non-breaking no changes (effectively nothing was changed) | update-schema-type-to-an-equivalent-value | |||||
| 132 | update-specific-type-to-number-with-exclusive-value | before after | update-specific-type-to-number-with-exclusive-value | |||||||
| 133 | additionalProperties.type. value | update-type-of-additional-properties | before after | breaking | breaking | Approved (Response Scope) | update-type-of-additional-properties | |||
| 134 | update-xml-name-replacement-for-property | before after | [not supported] breaking ? | requires attention | Approved (Response Scope) | update-xml-name-replacement-for-property | ||||
| 135 | update-xml-name-replacement-for-schema | (components.schema is necessary to define xml element name) | before after | [not supported] breaking ? | requires attention | Approved (Response Scope) | update-xml-name-replacement-for-schema | |||
| 136 | update-xml-prefix-for-schema | before after | [not supported] breaking ? | breaking ? | update-xml-prefix-for-schema |