Skip to content

Schema Changes

Felipe Tanabe edited this page Feb 5, 2026 · 14 revisions

Schema Changes

Scope Definitions

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

Changes Table

# Path ChangeID Comment Example ExpectedResultScopeRequest ExpectedResultScopeResponse Source Status Link
1 additionalProperties. value add-additional-props-with-false-value before after [not supported] breaking [Not Supported] add-additional-props-with-false-value
2 allOf add-all-of before after add-all-of
3 allOf. [*] add-all-of-option before after non-breaking non-breaking add-all-of-option
4 anyOf add-any-of before after non-breaking breaking Approved (Response Scope) add-any-of
5 anyOf. [*] add-any-of-option before after non-breaking breaking Approved (Response Scope) add-any-of-option
6 add-attribute-with-default-value-for-xml before after [not supported] [not supported] add-attribute-with-default-value-for-xml
7 .links.[*] . description add-description OAS links, ER shall define subsequent actions based on the response body -description adds context to the link before after [not applicable] annotation add-description
8 .discriminator.[*] add-discriminator before after [NOT SUPPORTED] non-breaking ? non-breaking Approved (Response Scope) add-discriminator
9 anyOf.discriminator.[*] add-discriminator-for-any-of [not applicable] add-discriminator-for-any-of
10 oneOf.discriminator.[*] add-discriminator-for-one-of [not applicable] add-discriminator-for-one-of
11 discriminator. mapping add-discriminator-mapping The mapping is added to the discriminator to explicitly link property values to schemas. before after non-breaking non-breaking add-discriminator-mapping
12 add-discriminator-mapping-element A new element is added to the mapping in the discriminator. before after non-breaking non-breaking? add-discriminator-mapping-element
13 enum add-enum before after breaking non-breaking Approved add-enum
14 enum. value add-enum-value before after non-breaking requires attention Approved add-enum-value
15 format. value add-format-for-number-property for number type before after breaking non-breaking Approved add-format-for-number-property
16 format. value add-format-for-string-property for string type before after breaking non-breaking Approved add-format-for-string-property
17 .links add-link OAS links, ER shall define subsequent actions based on the response -each link must reference a valid target operation before after [not applicable] non-breaking add-link
18 maxItems. value add-max-items-for-array-property for array type before after breaking non-breaking add-max-items-for-array-property
19 maxLength. value add-max-length-for-string-property for string type before after breaking non-breaking add-max-length-for-string-property
20 maxProperties. value add-max-properties-for-object-property for object type before after breaking non-breaking add-max-properties-for-object-property
21 maximum. value add-maximum-for-number-property for number type before after breaking non-breaking add-maximum-for-number-property
22 minItems. value add-min-items-for-array-property for array type before after breaking non-breaking add-min-items-for-array-property
23 (for array type) minItems. value add-min-items-with-default-value-for-array-property [not applicable] add-min-items-with-default-value-for-array-property
24 minLength. value add-min-length-for-string-property for string type before after breaking non-breaking add-min-length-for-string-property
25 minProperties. value add-min-properties-for-object-property for object type before after breaking non-breaking add-min-properties-for-object-property
26 (for object type) minProperties. value add-min-properties-with-default-value-for-object-property [not applicable] add-min-properties-with-default-value-for-object-property
27 minimum. value add-minimum-for-number-property for number type before after breaking non-breaking add-minimum-for-number-property
28 multiplyOf. value add-multiple-of-for-number-property for number type before after breaking non-breaking add-multiple-of-for-number-property
29 properties. value add-new-property for object type, this case is in compliance with additional properties before after non-breaking [NOT SUPPORTED] breaking add-new-property
30 properties. value add-new-property-compliance (compliance with additional properties ) before after non-breaking non-breaking Approved (Response Scope) add-new-property-compliance
31 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
32 oneOf add-one-of before after N non-breaking breaking Approved (Response Scope) add-one-of
33 oneOf. [*] add-one-of-option before after non-breaking breaking Approved (Response Scope) add-one-of-option
34 .links.[*] .parameters add-parameters OAS links, ER shall define subsequent actions based on the response body -parameters adds a map of parameters to pass before after [not applicable] non-breaking add-parameters
35 pattern. value add-pattern-for-string-property for string type before after breaking non-breaking add-pattern-for-string-property
36 required. value add-required-property for object type before after breaking non-breaking Approved (Response Scope) add-required-property
37 required. value add-required-property-with-default for object type before after breaking non-breaking Approved add-required-property-with-default
38 title. value add-schema-title before after annotation annotation add-schema-title
39 .links.[*] . server add-server OAS links, ER shall define subsequent actions based on the response body -server adds a server object before after [not applicable] non-breaking add-server
40 (for array type) uniqueItems. value add-unique-items-with-default-value-for-array-property [not applicable] add-unique-items-with-default-value-for-array-property
41 add-xml-name-replacement-for-property (default xml name the same as prop name) before after [not supported] breaking ? non-breaking Approved (Response Scope) add-xml-name-replacement-for-property
42 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
43 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
44 add-xml-wrapped-for-array-property before after [not supported] breaking ? breaking [not supported] add-xml-wrapped-for-array-property
45 add-xml-wrapped-with-default-value-for-array-property before after [not supported] [not supported] add-xml-wrapped-with-default-value-for-array-property
46 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
47 discriminator. propertyName update-discriminator-propertyName before after breaking breaking Approved update-discriminator-propertyName
48 maxItems. value decrease-max-items-for-array-property for array type before after breaking non-breaking decrease-max-items-for-array-property
49 maxLength. value decrease-max-length-for-string-property for string type before after breaking non-breaking decrease-max-length-for-string-property
50 maxProperties. value decrease-max-properties-for-object-property for object type before after breaking non-breaking decrease-max-properties-for-object-property
51 maximum. value decrease-maximum-for-number-property for number type before after breaking non-breaking decrease-maximum-for-number-property
52 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
53 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
54 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
55 minimum. value decrease-minimum-for-number-property for number type before after non-breaking requires attention Approved (Response Scope) decrease-minimum-for-number-property
56 maxItems. value increase-max-items-for-array-property for array type before after non-breaking breaking Approved (Response Scope) increase-max-items-for-array-property
57 maxLength. value increase-max-length-for-string-property for string type before after non-breaking breaking Approved (Response Scope) increase-max-length-for-string-property
58 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
59 maximum. value increase-maximum-for-number-property for number type before after non-breaking requires attention Approved (Response Scope) increase-maximum-for-number-property
60 minItems. value increase-min-items-for-array-property for array type before after breaking non-breaking increase-min-items-for-array-property
61 minLength. value increase-min-length-for-string-property for string type before after breaking non-breaking increase-min-length-for-string-property
62 minProperties. value increase-min-properties-for-object-property for object type before after breaking non-breaking increase-min-properties-for-object-property
63 minimum. value increase-minimum-for-number-property for number type before after breaking non-breaking increase-minimum-for-number-property
64 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
65 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
66 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
67 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
68 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
69 writeOnly. value mark-object-property-as-not-write-only before after non-breaking non-breaking mark-object-property-as-not-write-only
70 readOnly. value mark-object-property-as-read-only for object type before after breaking non-breaking mark-object-property-as-read-only
71 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
72 mark-property-as-xml-attribute before after [not supported] breaking requires attention Approved (Response Scope) mark-property-as-xml-attribute
73 mark-property-as-xml-element before after [not supported] breaking ? non-breaking Approved (Response Scope) mark-property-as-xml-element
74 nullable. value mark-schema-value-as-non-nullable before after breaking [not applicable] mark-schema-value-as-non-nullable
75 nullable. value mark-schema-value-as-nullable before after non-breaking breaking Approved (Request Scope) mark-schema-value-as-nullable
76 allOf.[*] non-breaking before after non-breaking non-breaking non-breaking
77 uniqueItems. value prohibit-non-unique-items-for-array-property for array type before after breaking non-breaking prohibit-non-unique-items-for-array-property
78 additionalProperties.type. value remove-additional-properties before after breaking breaking Approved (Response Scope) remove-additional-properties
79 additionalProperties. value remove-additional-props-with-false-value before after [not supported] non-breaking [Not Supported] remove-additional-props-with-false-value
80 allOf. [*] remove-all-of remove allOf + one of the object inside allOf before after breaking (breaking of functionality) non-breaking remove-all-of
81 allOf. [*] remove-all-of-option before after breaking (breaking of functionality) non-breaking remove-all-of-option
82 anyOf. [*] remove-any-of remove anyOf + one of the object inside anyOf before after breaking non-breaking remove-any-of
83 anyOf. [*] remove-any-of-option before after breaking non-breaking remove-any-of-option
84 remove-attribute-with-default-value-for-xml before after [not supported] [not supported] remove-attribute-with-default-value-for-xml
85 remove-description OAS links, ER shall define subsequent actions based on the response body -description is removed before after [not applicable] annotation remove-description
86 remove-discriminator before after [NOT SUPPORTED] non-breaking ? non-breaking Approved (Response Scope) remove-discriminator
87 remove-discriminator-for-any-of [not applicable] remove-discriminator-for-any-of
88 remove-discriminator-for-one-of [not applicable] remove-discriminator-for-one-of
89 remove-discriminator-mapping The mapping is removed from the discriminator, reverting to default behavior before after requires attention requires attention Approved remove-discriminator-mapping
90 remove-discriminator-mapping-element One element is removed from the mapping in the discriminator. before after breaking non-breaking Approved (Response Scope) remove-discriminator-mapping-element
91 enum remove-enum before after non-breaking breaking Approved remove-enum
92 enum. value remove-enum-value before after breaking requires attention Approved remove-enum-value
93 format. value remove-format-for-number-property for number type before after non-breaking breaking Approved remove-format-for-number-property
94 format. value remove-format-for-string-property for string type before after non-breaking breaking Approved remove-format-for-string-property
95 remove-link OAS links, ER shall define subsequent actions based on the response -each link must reference a valid target operation before after [not applicable] breaking remove-link
96 maxItems. value remove-max-items-for-array-property for array type before after non-breaking breaking Approved (Response Scope) remove-max-items-for-array-property
97 maxLength. value remove-max-length-for-string-property for string type before after non-breaking breaking Approved (Response Scope) remove-max-length-for-string-property
98 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
99 maximum. value remove-maximum-for-number-property for number type before after non-breaking requires attention Approved (Response Scope) remove-maximum-for-number-property
100 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
101 remove-min-items-with-default-value-for-array-property [not applicable] remove-min-items-with-default-value-for-array-property
102 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
103 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
104 remove-min-properties-with-default-value-for-object-property [not applicable] remove-min-properties-with-default-value-for-object-property
105 minimum. value remove-minimum-for-number-property for number type before after non-breaking requires attention Approved (Response Scope) remove-minimum-for-number-property
106 multiplyOf. value remove-multiple-of-for-number-property for number type before after non-breaking breaking ? remove-multiple-of-for-number-property
107 oneOf remove-one-of remove oneOf + one of the object inside oneOf before after N breaking N non-breaking remove-one-of
108 oneOf. [*] remove-one-of-option before after breaking non-breaking remove-one-of-option
109 remove-parameters OAS links, ER shall define subsequent actions based on the response body -parameters is removed before after [not applicable] breaking remove-parameters
110 pattern. value remove-pattern-for-string-property for string type before after non-breaking breaking Approved (Response Scope) remove-pattern-for-string-property
111 properties. value remove-property for object type, this case is in compliance with additional properties before after breaking (breaking of functionality) [NOT SUPPORTED] non-breaking remove-property
112 properties. value remove-property-compliance before after non-breaking non-breaking Approved remove-property-compliance
113 required. value remove-required-property for object type before after non-breaking breaking Approved (Response Scope) remove-required-property
114 required. value remove-required-property-compliance (compliance with additional properties) before after breaking breaking Approved remove-required-property-compliance
115 title. value remove-schema-title before after annotation annotation remove-schema-title
116 remove-server OAS links, ER shall define subsequent actions based on the response body -server is removed before after [not applicable] breaking remove-server
117 remove-unique-items-with-default-value-for-array-property [not applicable] remove-unique-items-with-default-value-for-array-property
118 remove-xml-name-replacement-for-property before after [not supported] breaking ? requires attention Approved (Response Scope) remove-xml-name-replacement-for-property
119 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
120 remove-xml-prefix-and-namespace-for-schema before after [not supported] 2 breaking ? breaking ? remove-xml-prefix-and-namespace-for-schema
121 remove-xml-wrapped-for-array-property before after [not supported] breaking ? breaking [not supported] remove-xml-wrapped-for-array-property
122 remove-xml-wrapped-with-default-value-for-array-property before after before after [not supported] [not supported] remove-xml-wrapped-with-default-value-for-array-property
123 additionalProperties. value update-additional-props-from-any-to-false before after [not supported] breaking [Not Supported] update-additional-props-from-any-to-false
124 additionalProperties. value update-additional-props-from-false-to-any before after [not supported] non-breaking [Not Supported] update-additional-props-from-false-to-any
125 additionalProperties. value update-additional-props-from-false-to-some-type before after [not supported] non-breaking [Not Supported] update-additional-props-from-false-to-some-type
126 additionalProperties. value update-additional-props-from-false-to-true before after [not supported] non-breaking [Not Supported] update-additional-props-from-false-to-true
127 additionalProperties.type. value update-additional-props-from-some-type-to-false before after [not supported] breaking [Not Supported] update-additional-props-from-some-type-to-false
128 additionalProperties. value update-additional-props-from-true-to-false before after [not supported] breaking [Not Supported] update-additional-props-from-true-to-false
129 anyOf update-combiner-key-from-anyof-to-empty-oneof anyOf [1, 2] -> oneOf[] before after [not supported] non-breaking breaking Approved (Response Scope) update-combiner-key-from-anyof-to-empty-oneof
130 anyOf update-combiner-key-from-anyof-to-oneof change only combiner key before after [not supported] breaking breaking Approved (Response Scope) update-combiner-key-from-anyof-to-oneof
131 anyOf update-combiner-key-from-anyof-to-oneof-and-update-content anyOf [1, 2] -> oneOf [3, 4, 5] before after breaking breaking Approved update-combiner-key-from-anyof-to-oneof-and-update-content
132 oneOf update-combiner-key-from-oneof-to-anyof change only combiner key before after [not supported] breaking breaking Approved (Response Scope) update-combiner-key-from-oneof-to-anyof
133 oneOf update-combiner-key-from-oneof-to-anyof-and-update-content oneOf [1, 2] -> anyOf [3, 4, 5] before after [not supported] breaking breaking Approved (Response Scope) update-combiner-key-from-oneof-to-anyof-and-update-content
134 oneOf update-combiner-key-from-oneof-to-empty-anyof oneOf [1, 2] -> anyOf[] before after [not supported] non-breaking breaking Approved (Response Scope) update-combiner-key-from-oneof-to-empty-anyof
135 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
136 update-description OAS links, ER shall define subsequent actions based on the response body -description is updated before after [not applicable] annotation update-description
137 update-discriminator before after [NOT SUPPORTED] non-breaking ? [NOT SUPPORTED] breaking ? update-discriminator
138 update-discriminator-for-any-of [not applicable] update-discriminator-for-any-of
139 update-discriminator-for-one-of [not applicable] update-discriminator-for-one-of
140 update-discriminator-mapping The mapping is updated to point to different schemas. before after breaking breaking Approved (Response Scope) update-discriminator-mapping
141 update-discriminator-mapping-element One element in the mapping is updated in the discriminator. before after breaking breaking Approved (Response Scope) update-discriminator-mapping-element
142 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
143 format. value update-format-for-number-property for number type before after breaking breaking Approved update-format-for-number-property
144 format. value update-format-for-string-property for string type before after breaking breaking Approved update-format-for-string-property
145 anyOf update-from-empty-anyof-to-oneof-with-content anyOf[] -> oneOf [1, 2] before after [not supported] breaking requires attention Approved (Response Scope) update-from-empty-anyof-to-oneof-with-content
146 oneOf update-from-empty-oneof-to-anyof-with-content oneOf[] -> anyOf [1, 2] cases was added in scope of APIHUB-10061 before after breaking breaking Approved update-from-empty-oneof-to-anyof-with-content
147 update-link OAS links, ER shall define subsequent actions based on the response -each link must reference a valid target operation before after [not applicable] breaking update-link
148 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
149 update-parameters OAS links, ER shall define subsequent actions based on the response body -parameters is updated to pass different values before after [not applicable] breaking update-parameters
150 pattern. value update-pattern-for-string-property for string type before after breaking breaking Approved (Response Scope) update-pattern-for-string-property
151 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
152 title. value update-schema-title before after annotation annotation update-schema-title
153 type. value update-schema-type before after breaking breaking Approved update-schema-type
154 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
155 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
156 update-schema-type-from-nothing-type-to-string-type before after [not applicable] [not supported] non-breaking update-schema-type-from-nothing-type-to-string-type
157 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
158 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
159 update-schema-type-from-string-type-to-nothing-type before after [not applicable] breaking Approved (Response Scope) update-schema-type-from-string-type-to-nothing-type
160 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
161 update-server OAS links, ER shall define subsequent actions based on the response body -server is updated to point to a different server before after [not applicable] breaking update-server
162 additionalProperties.type. value update-type-of-additional-properties before after breaking breaking Approved (Response Scope) update-type-of-additional-properties
163 update-xml-name-replacement-for-property before after [not supported] breaking ? requires attention Approved (Response Scope) update-xml-name-replacement-for-property
164 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
165 update-xml-prefix-for-schema before after [not supported] breaking ? breaking ? update-xml-prefix-for-schema

Clone this wiki locally