Schema validation changes

Schema Validation Changes

There are new schema validations going to be performed everytime there is a create or update request. These changes are driven by below rules:

SchemaChanges

• Schema Changes
• Schema Service
  • Permitted Changes for PATCH Version Increments
  • Permitted Changes for MINOR Version Increments
  • Permitted Changes for MAJOR Version Increments

Schema Changes

Schema modifications have to be done with great care as schemas can be used to generate code and API specifications. Changes may or may not break clients consuming the schemas.

The solution to this is the concept of semantic versioning. General rules have been defined during the R3 cycle in this summary:

• Given a version number MAJOR.MINOR.PATCH, increment the:
  • MAJOR version when you make incompatible schema changes,
  • MINOR version when you add functionality or contents in a backwards compatible manner, and
  • PATCH version when you make backwards compatible bug fixes or documentation/decoration changes.

Schema Service

New schemas are registered with the Schema service. The Schema service checks the incoming schema definition against the previous minor and/or patch version should they exist.

Permitted Changes for PATCH Version Increments

Changes to the values (text) of the following JSON tags:

1. title
2. description
3. example
4. pattern
5. $id
6. $comment
7. any JSON extension tag starting with x-osdu

Permitted Changes for MINOR Version Increments

In addition to all permitted changes in PATCH versions, the following actions are permitted:

1. adding properties to existing data and nested structures
2. adding object structures to
   1. allOf arrays and
   2. oneOf arrays.

Explicitly not permitted is changing

1. the list of required properties
2. the state of additionalProperties.

It is permitted to declare existing properties as deprecated, preferable with instructions how to migrate from the previous to the next version. The documentation will automatically mark properties with strike-through if the description starts with "DEPRECATED: ".

Permitted Changes for MAJOR Version Increments

Any changes are permitted, specifically

• removal of properties
• removal of structures in allOf, oneOf
• changing the list of required properties
• changing the state of additionalProperties.