Skip to content

Schema Changes

Adil Bektursunov edited this page Dec 17, 2025 · 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 Approved Link
additionalProperties. value add-additional-props-with-false-value before after [not supported] breaking [Not Supported] Common (all 4) add-additional-props-with-false-value
allOf add-all-of before after Parameters, ResponseHeaders add-all-of
allOf. [*] add-all-of-option before after non-breaking non-breaking Common (all 4) add-all-of-option
anyOf add-any-of before after non-breaking breaking Common (all 4) add-any-of
anyOf. [*] add-any-of-option before after non-breaking breaking Common (all 4) add-any-of-option
add-attribute-with-default-value-for-xml before after [not supported] [not supported] Common (all 4) add-attribute-with-default-value-for-xml
.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 ResponseBody add-description
.discriminator.[*] add-discriminator before after [NOT SUPPORTED] non-breaking ? [NOT SUPPORTED] breaking ? Parameters, RequestBody, ResponseBody add-discriminator
anyOf.discriminator.[*] add-discriminator-for-any-of [not applicable] ResponseHeaders add-discriminator-for-any-of
oneOf.discriminator.[*] add-discriminator-for-one-of [not applicable] ResponseHeaders add-discriminator-for-one-of
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 Parameters, RequestBody, ResponseBody add-discriminator-mapping
add-discriminator-mapping-element A new element is added to the mapping in the discriminator. before after non-breaking non-breaking? Parameters, RequestBody, ResponseBody add-discriminator-mapping-element
enum add-enum before after breaking non-breaking Common (all 4) add-enum
enum. value add-enum-value before after non-breaking requires attention Common (all 4) add-enum-value
format. value add-format-for-number-property for number type before after breaking non-breaking Common (all 4) add-format-for-number-property
format. value add-format-for-string-property for string type before after breaking non-breaking Common (all 4) add-format-for-string-property
.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 ResponseBody add-link
maxItems. value add-max-items-for-array-property for array type before after breaking non-breaking Common (all 4) add-max-items-for-array-property
maxLength. value add-max-length-for-string-property for string type before after breaking non-breaking Common (all 4) add-max-length-for-string-property
maxProperties. value add-max-properties-for-object-property for object type before after breaking non-breaking Common (all 4) add-max-properties-for-object-property
maximum. value add-maximum-for-number-property for number type before after breaking non-breaking Common (all 4) add-maximum-for-number-property
minItems. value add-min-items-for-array-property for array type before after breaking non-breaking Common (all 4) add-min-items-for-array-property
(for array type) minItems. value add-min-items-with-default-value-for-array-property [not applicable] ResponseHeaders add-min-items-with-default-value-for-array-property
minLength. value add-min-length-for-string-property for string type before after breaking non-breaking Common (all 4) add-min-length-for-string-property
minProperties. value add-min-properties-for-object-property for object type before after breaking non-breaking Common (all 4) add-min-properties-for-object-property
(for object type) minProperties. value add-min-properties-with-default-value-for-object-property [not applicable] ResponseHeaders add-min-properties-with-default-value-for-object-property
minimum. value add-minimum-for-number-property for number type before after breaking non-breaking Common (all 4) add-minimum-for-number-property
multiplyOf. value add-multiple-of-for-number-property for number type before after breaking non-breaking Common (all 4) add-multiple-of-for-number-property
properties. value add-new-property for object type, this case is in compliance with additional properties before after non-breaking [NOT SUPPORTED] breaking Common (all 4) add-new-property
properties. value add-new-property-compliance (compliance with additional properties ) before after non-breaking non-breaking RequestBody, ResponseBody add-new-property-compliance
additionalProperties.type. value add-non-boolean-additional-properties i.e. define dictionary with value of specific type before after breaking breaking Common (all 4) add-non-boolean-additional-properties
oneOf add-one-of before after N non-breaking breaking Common (all 4) add-one-of
oneOf. [*] add-one-of-option before after non-breaking breaking Common (all 4) add-one-of-option
.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 ResponseBody add-parameters
pattern. value add-pattern-for-string-property for string type before after breaking non-breaking Common (all 4) add-pattern-for-string-property
required. value add-required-property for object type before after breaking non-breaking Common (all 4) add-required-property
required. value add-required-property-with-default for object type before after non-breaking non-breaking Common (all 4) add-required-property-with-default
title. value add-schema-title before after annotation annotation Common (all 4) add-schema-title
.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 ResponseBody add-server
(for array type) uniqueItems. value add-unique-items-with-default-value-for-array-property [not applicable] ResponseHeaders add-unique-items-with-default-value-for-array-property
add-xml-name-replacement-for-property (default xml name the same as prop name) before after [not supported] breaking ? breaking ? Common (all 4) add-xml-name-replacement-for-property
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 ? breaking ? Common (all 4) add-xml-name-replacement-for-schema
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 ? Common (all 4) add-xml-prefix-and-namespace-for-schema
add-xml-wrapped-for-array-property before after [not supported] breaking ? breaking [not supported] Common (all 4) add-xml-wrapped-for-array-property
add-xml-wrapped-with-default-value-for-array-property before after [not supported] [not supported] Common (all 4) add-xml-wrapped-with-default-value-for-array-property
uniqueItems. value allow-non-unique-items-for-array-property for array type before after non-breaking breaking Common (all 4) allow-non-unique-items-for-array-property
discriminator. propertyName breaking update-discriminator-propertyName before after breaking breaking Parameters, RequestBody, ResponseBody breaking
maxItems. value decrease-max-items-for-array-property for array type before after breaking non-breaking Common (all 4) decrease-max-items-for-array-property
maxLength. value decrease-max-length-for-string-property for string type before after breaking non-breaking Common (all 4) decrease-max-length-for-string-property
maxProperties. value decrease-max-properties-for-object-property for object type before after breaking non-breaking Common (all 4) decrease-max-properties-for-object-property
maximum. value decrease-maximum-for-number-property for number type before after breaking non-breaking Common (all 4) decrease-maximum-for-number-property
minItems. value decrease-min-items-for-array-property for array type before after non-breaking breaking Common (all 4) decrease-min-items-for-array-property
minLength. value decrease-min-length-for-string-property for string type before after non-breaking breaking Common (all 4) decrease-min-length-for-string-property
minProperties. value decrease-min-properties-for-object-property for object type before after non-breaking breaking Common (all 4) decrease-min-properties-for-object-property
minimum. value decrease-minimum-for-number-property for number type before after non-breaking breaking Common (all 4) decrease-minimum-for-number-property
maxItems. value increase-max-items-for-array-property for array type before after non-breaking breaking Common (all 4) increase-max-items-for-array-property
maxLength. value increase-max-length-for-string-property for string type before after non-breaking breaking Common (all 4) increase-max-length-for-string-property
maxProperties. value increase-max-properties-for-object-property for object type before after non-breaking breaking Common (all 4) increase-max-properties-for-object-property
maximum. value increase-maximum-for-number-property for number type before after non-breaking breaking Common (all 4) increase-maximum-for-number-property
minItems. value increase-min-items-for-array-property for array type before after breaking non-breaking Common (all 4) increase-min-items-for-array-property
minLength. value increase-min-length-for-string-property for string type before after breaking non-breaking Common (all 4) increase-min-length-for-string-property
minProperties. value increase-min-properties-for-object-property for object type before after breaking non-breaking Common (all 4) increase-min-properties-for-object-property
minimum. value increase-minimum-for-number-property for number type before after breaking non-breaking Common (all 4) increase-minimum-for-number-property
exclusiveMaximum. value mark-maximum-value-as-exclusive-for-number-property for number type before after breaking + non-breaking non-breaking Common (all 4) mark-maximum-value-as-exclusive-for-number-property
exclusiveMaximum. value mark-maximum-value-as-inclusive-for-number-property for number type before after non-breaking breaking Common (all 4) mark-maximum-value-as-inclusive-for-number-property
exclusiveMinimum. value mark-minimum-value-as-exclusive-for-number-property for number type before after breaking + non-breaking non-breaking Common (all 4) mark-minimum-value-as-exclusive-for-number-property
minimum. value mark-minimum-value-as-inclusive-for-number-property for number type before after non-breaking breaking Common (all 4) mark-minimum-value-as-inclusive-for-number-property
readOnly. value mark-object-property-as-not-read-only for object type before after non-breaking non-breaking Common (all 4) mark-object-property-as-not-read-only
writeOnly. value mark-object-property-as-not-write-only before after non-breaking non-breaking Common (all 4) mark-object-property-as-not-write-only
readOnly. value mark-object-property-as-read-only for object type before after breaking non-breaking Common (all 4) mark-object-property-as-read-only
writeOnly. value mark-object-property-as-write-only writeOnly properties may be sent only in requests before after non-breaking non-breaking Common (all 4) mark-object-property-as-write-only
mark-property-as-xml-attribute before after [not supported] breaking breaking ? Common (all 4) mark-property-as-xml-attribute
mark-property-as-xml-element before after [not supported] breaking ? breaking ? Common (all 4) mark-property-as-xml-element
nullable. value mark-schema-value-as-non-nullable before after breaking [not applicable] Parameters, RequestBody mark-schema-value-as-non-nullable
nullable. value mark-schema-value-as-nullable before after non-breaking breaking Common (all 4) mark-schema-value-as-nullable
allOf.[*] non-breaking before after non-breaking non-breaking RequestBody, ResponseBody non-breaking
uniqueItems. value prohibit-non-unique-items-for-array-property for array type before after breaking non-breaking Common (all 4) prohibit-non-unique-items-for-array-property
additionalProperties.type. value remove-additional-properties before after breaking breaking Common (all 4) remove-additional-properties
additionalProperties. value remove-additional-props-with-false-value before after [not supported] non-breaking [Not Supported] Common (all 4) remove-additional-props-with-false-value
allOf. [*] remove-all-of remove allOf + one of the object inside allOf before after breaking (breaking of functionality) non-breaking Common (all 4) remove-all-of
allOf. [*] remove-all-of-option before after breaking (breaking of functionality) non-breaking Common (all 4) remove-all-of-option
anyOf. [*] remove-any-of remove anyOf + one of the object inside anyOf before after breaking non-breaking Common (all 4) remove-any-of
anyOf. [*] remove-any-of-option before after breaking non-breaking Common (all 4) remove-any-of-option
remove-attribute-with-default-value-for-xml before after [not supported] [not supported] Common (all 4) remove-attribute-with-default-value-for-xml
remove-description OAS links, ER shall define subsequent actions based on the response body -description is removed before after [not applicable] annotation ResponseBody remove-description
remove-discriminator before after [NOT SUPPORTED] non-breaking ? [NOT SUPPORTED] breaking ? Parameters, RequestBody, ResponseBody remove-discriminator
remove-discriminator-for-any-of [not applicable] ResponseHeaders remove-discriminator-for-any-of
remove-discriminator-for-one-of [not applicable] ResponseHeaders remove-discriminator-for-one-of
remove-discriminator-mapping The mapping is removed from the discriminator, reverting to default behavior before after breaking breaking Parameters, RequestBody, ResponseBody remove-discriminator-mapping
remove-discriminator-mapping-element One element is removed from the mapping in the discriminator. before after breaking breaking Parameters, RequestBody, ResponseBody remove-discriminator-mapping-element
enum remove-enum before after non-breaking breaking Common (all 4) remove-enum
enum. value remove-enum-value before after breaking non-breaking Common (all 4) remove-enum-value
format. value remove-format-for-number-property for number type before after non-breaking breaking Common (all 4) remove-format-for-number-property
format. value remove-format-for-string-property for string type before after non-breaking breaking Common (all 4) remove-format-for-string-property
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 ResponseBody remove-link
maxItems. value remove-max-items-for-array-property for array type before after non-breaking breaking Common (all 4) remove-max-items-for-array-property
maxLength. value remove-max-length-for-string-property for string type before after non-breaking breaking Common (all 4) remove-max-length-for-string-property
maxProperties. value remove-max-properties-for-object-property for object type before after non-breaking breaking Common (all 4) remove-max-properties-for-object-property
maximum. value remove-maximum-for-number-property for number type before after non-breaking breaking Common (all 4) remove-maximum-for-number-property
minItems. value remove-min-items-for-array-property for array type before after non-breaking breaking Common (all 4) remove-min-items-for-array-property
remove-min-items-with-default-value-for-array-property [not applicable] ResponseHeaders remove-min-items-with-default-value-for-array-property
minLength. value remove-min-length-for-string-property for string type before after non-breaking breaking Common (all 4) remove-min-length-for-string-property
minProperties. value remove-min-properties-for-object-property for object type before after non-breaking breaking Common (all 4) remove-min-properties-for-object-property
remove-min-properties-with-default-value-for-object-property [not applicable] ResponseHeaders remove-min-properties-with-default-value-for-object-property
minimum. value remove-minimum-for-number-property for number type before after non-breaking breaking Common (all 4) remove-minimum-for-number-property
multiplyOf. value remove-multiple-of-for-number-property for number type before after non-breaking breaking ? Common (all 4) remove-multiple-of-for-number-property
oneOf remove-one-of remove oneOf + one of the object inside oneOf before after N breaking N non-breaking Common (all 4) remove-one-of
oneOf. [*] remove-one-of-option before after breaking non-breaking Common (all 4) remove-one-of-option
remove-parameters OAS links, ER shall define subsequent actions based on the response body -parameters is removed before after [not applicable] breaking ResponseBody remove-parameters
pattern. value remove-pattern-for-string-property for string type before after non-breaking breaking Common (all 4) remove-pattern-for-string-property
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 Common (all 4) remove-property
properties. value remove-property-compliance [before](https://github.com/Netcracker/qubership-apihub-compatibility-suites/blob/develop/bin/comparison-base-suite/openapi/request-body-schema/remove-property- compliance/before.yaml) [after](https://github.com/Netcracker/qubership-apihub-compatibility-suites/blob/develop/bin/comparison-base-suite/openapi/request-body-schema/remove-property- compliance/after.yaml) breaking (breaking in functionality) non-breaking RequestBody, ResponseBody remove-property-compliance
required. value remove-required-property for object type before after non-breaking breaking Common (all 4) remove-required-property
title. value remove-schema-title before after annotation annotation Common (all 4) remove-schema-title
remove-server OAS links, ER shall define subsequent actions based on the response body -server is removed before after [not applicable] breaking ResponseBody remove-server
remove-unique-items-with-default-value-for-array-property [not applicable] ResponseHeaders remove-unique-items-with-default-value-for-array-property
remove-xml-name-replacement-for-property before after [not supported] breaking ? breaking ? Common (all 4) remove-xml-name-replacement-for-property
remove-xml-name-replacement-for-schema (components.schema is necessary to define xml element name) before after [not supported] breaking ? breaking ? Common (all 4) remove-xml-name-replacement-for-schema
remove-xml-prefix-and-namespace-for-schema before after [not supported] 2 breaking ? breaking ? Common (all 4) remove-xml-prefix-and-namespace-for-schema
remove-xml-wrapped-for-array-property before after [not supported] breaking ? breaking [not supported] Common (all 4) remove-xml-wrapped-for-array-property
remove-xml-wrapped-with-default-value-for-array-property before after before after [not supported] [not supported] Common (all 4) remove-xml-wrapped-with-default-value-for-array-property
additionalProperties. value update-additional-props-from-any-to-false before after [not supported] breaking [Not Supported] Common (all 4) update-additional-props-from-any-to-false
additionalProperties. value update-additional-props-from-false-to-any before after [not supported] non-breaking [Not Supported] Common (all 4) update-additional-props-from-false-to-any
additionalProperties. value update-additional-props-from-false-to-some-type before after [not supported] non-breaking [Not Supported] Common (all 4) update-additional-props-from-false-to-some-type
additionalProperties. value update-additional-props-from-false-to-true before after [not supported] non-breaking [Not Supported] Common (all 4) update-additional-props-from-false-to-true
additionalProperties.type. value update-additional-props-from-some-type-to-false before after [not supported] breaking [Not Supported] Common (all 4) update-additional-props-from-some-type-to-false
additionalProperties. value update-additional-props-from-true-to-false before after [not supported] breaking [Not Supported] Common (all 4) update-additional-props-from-true-to-false
anyOf update-combiner-key-from-anyof-to-empty-oneof anyOf [1, 2] -> oneOf[] before after [not supported] non-breaking breaking Common (all 4) update-combiner-key-from-anyof-to-empty-oneof
anyOf update-combiner-key-from-anyof-to-oneof change only combiner key before after [not supported] breaking breaking Common (all 4) update-combiner-key-from-anyof-to-oneof
anyOf update-combiner-key-from-anyof-to-oneof-and-update-content anyOf [1, 2] -> oneOf [3, 4, 5] before after [not supported] breaking breaking Common (all 4) update-combiner-key-from-anyof-to-oneof-and-update-content
oneOf update-combiner-key-from-oneof-to-anyof change only combiner key before after [not supported] breaking breaking Common (all 4) update-combiner-key-from-oneof-to-anyof
oneOf update-combiner-key-from-oneof-to-anyof-and-update-content oneOf [1, 2] -> anyOf [3, 4, 5] before after [not supported] breaking breaking Common (all 4) update-combiner-key-from-oneof-to-anyof-and-update-content
oneOf update-combiner-key-from-oneof-to-empty-anyof oneOf [1, 2] -> anyOf[] before after [not supported] non-breaking breaking Common (all 4) update-combiner-key-from-oneof-to-empty-anyof
additionalProperties. value update-definition-of-free-form-object for object type before after non-breaking ? non-breaking no changes (effectively nothing was changed) Common (all 4) update-definition-of-free-form-object
update-description OAS links, ER shall define subsequent actions based on the response body -description is updated before after [not applicable] annotation ResponseBody update-description
update-discriminator before after [NOT SUPPORTED] non-breaking ? [NOT SUPPORTED] breaking ? Parameters, RequestBody, ResponseBody update-discriminator
update-discriminator-for-any-of [not applicable] ResponseHeaders update-discriminator-for-any-of
update-discriminator-for-one-of [not applicable] ResponseHeaders update-discriminator-for-one-of
update-discriminator-mapping The mapping is updated to point to different schemas. before after breaking breaking Parameters, RequestBody, ResponseBody update-discriminator-mapping
update-discriminator-mapping-element One element in the mapping is updated in the discriminator. before after breaking breaking Parameters, RequestBody, ResponseBody update-discriminator-mapping-element
enum. value update-enum-value before after 1 breaking (for removed enum) and 1 non-breaking (for added enum) ? 1 breaking (for added enum value) and 1 non-breaking (for deleted enum value) Common (all 4) update-enum-value
format. value update-format-for-number-property for number type before after breaking breaking ? Common (all 4) update-format-for-number-property
format. value update-format-for-string-property for string type before after breaking breaking ? Common (all 4) update-format-for-string-property
anyOf update-from-empty-anyof-to-oneof-with-content anyOf[] -> oneOf [1, 2] before after [not supported] breaking breaking Common (all 4) update-from-empty-anyof-to-oneof-with-content
oneOf update-from-empty-oneof-to-anyof-with-content oneOf[] -> anyOf [1, 2] cases was added in scope of APIHUB-10061 before after [not supported] breaking breaking Common (all 4) update-from-empty-oneof-to-anyof-with-content
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 ResponseBody update-link
multiplyOf. value update-multiple-of-for-number-property for number type before after breaking breaking Common (all 4) update-multiple-of-for-number-property
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 ResponseBody update-parameters
pattern. value update-pattern-for-string-property for string type before after breaking breaking Common (all 4) update-pattern-for-string-property
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 Common (all 4) update-required-property
title. value update-schema-title before after annotation annotation Common (all 4) update-schema-title
type. value update-schema-type before after breaking breaking Common (all 4) update-schema-type
type. value update-schema-type-from-any-type-to-specific-type before after [not supported] breaking [not supported] non-breaking Parameters, RequestBody, ResponseBody update-schema-type-from-any-type-to-specific-type
type. value update-schema-type-from-nothing-to-specific-type before after [not supported] non-breaking [not applicable] Parameters, RequestBody update-schema-type-from-nothing-to-specific-type
update-schema-type-from-nothing-type-to-string-type before after [not applicable] [not supported] non-breaking ResponseBody update-schema-type-from-nothing-type-to-string-type
type. value update-schema-type-from-specific-type-to-any-type before after non-breaking breaking Common (all 4) update-schema-type-from-specific-type-to-any-type
type. value update-schema-type-from-specific-type-to-nothing before after [not supported] breaking [not applicable] Parameters, RequestBody update-schema-type-from-specific-type-to-nothing
update-schema-type-from-string-type-to-nothing-type before after [not applicable] [not supported] breaking ResponseBody update-schema-type-from-string-type-to-nothing-type
type. value update-schema-type-to-an-equivalent-value before after non-breaking no changes (effectively nothing was changed) Common (all 4) update-schema-type-to-an-equivalent-value
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 ResponseBody update-server
additionalProperties.type. value update-type-of-additional-properties before after breaking breaking Common (all 4) update-type-of-additional-properties
update-xml-name-replacement-for-property before after [not supported] breaking ? breaking ? Common (all 4) update-xml-name-replacement-for-property
update-xml-name-replacement-for-schema (components.schema is necessary to define xml element name) before after [not supported] breaking ? breaking ? Common (all 4) update-xml-name-replacement-for-schema
update-xml-prefix-for-schema before after [not supported] breaking ? breaking ? Common (all 4) update-xml-prefix-for-schema

Clone this wiki locally