Versioning data and schema

[dmethvin-gov]

Often the schema for collected data might change over time, for example, to add, change, or remove fields. When that happens the front-end and back-end code need to agree on which "version" of they form data they are working with. That is especially true if it the user can save intermediate data (partially completed forms) to the server, or if the completed form is saved to individual fields in a SQL database for example.

The JSON Schema standard defines a $schema property and the vets.gov schemas define it, but that specifies the version of the schema itself--not the data being validated by the schema.

Some folks have created a SchemaVer to address the issue. It's similar to SemVer used in software, but looks like MODEL-REVISION-ADDITION, i.e. dashes instead of dots. The wiki spec and associated blog post have examples of schema changes and the version updates they require. Quoting the SchemaVer page linked above:

• MODEL when you make a breaking schema change which will prevent interaction with any historical data
• REVISION when you introduce a schema change which may prevent interaction with some historical data
• ADDITION when you make a schema change that is compatible with all historical data

We should encourage use of a SchemaVer in the schema to help form creators understand this issue and ensure they don't save incompatible form data in their backend.

[jcmeloni-usds]

I like it!

[jcmeloni-usds]

@dmethvin-gov Going to make this a later-phase item to address via documentation or otherwise.

[dmethvin-gov]

This was a nice-to-have but not needed.