Schema Definition - Version support

Owned by Amit Priyadarshi
Oct 25, 2019

Problem Definition:

This document is written to propose a design to better manage the definition updates that are created, 
used and removed during the lifecycle of a schemas.


Background & Problem Statement:

In KP, the intention is to keep the published definition separate from the other changed versions. 
So, whenever a definition is retrieved, the latest published definition should be retrieved allowing 
to keep the changed definition intact without getting overwritten.

Key Design Problems:

  • A simple schema defintion format
  • Easier way to update schema definition
  • Keep updated definition separate from the older definitions until publishe
  • Avoid changing the json definition in the conf folder

Design:

The basic idea is to create 2 locations for updated versions of the definition and published versions of definitions:

So, the idea is keep the process consistent with the rest of the process. The schema definition json file will have the following properties:
  • $id - defines a URI for the schema, and the base URI that other URI references within the schema are resolved against
  • $schema - states that this schema is written according to a specific draft of the standard and used for a variety of reasons, primarily version control
  • title - the intent of the schema is stated by this
  • type - defines the first constraint on our JSON data and in this case it has to be a JSON Object
  • properties - this will have artifactURL and downloadURL properties
    • artifactURL - this link will point to a file describing the detailed properties of the schema
    • downloadURL - this will point to the file file to be used after publishing the changes to schema
  • required - this will tell the required properties. In this case, both artifactURL and downloadURL are mandatory

Process Flow:

Whenever a release happens, the document versions of the artifactURL and the downloadURL will be same. Whenever there are 
updates to be made to the schemas, the current copy of the document available in artifactURL will be replaced by a copy of the 
document available in downloadURL. This would be the document with the latest changes in it until the changes are published.
Once, the document at artifactURL will be moved to the downloadURL location and the previous copy present at downloadURL will be 
stored with *<filename>.bk* added to it. Once published, the document at artifactURL will be same as downloadURL.
This way, we need not change the schema.json each time as it will keep pointing to the same URL and the document available at 
that URL will always be the latest published document.