Schema Versioning


I have a schema with additional properties: true
and I want to add a new property and change additional properties to false

Do I have then to iterate then to 2-0-0. ?

Sorry if this is maybe a trivial one, but I read the blog post about SchemVar… and i can not figure it out.


Hi @julianDii - yes, you should bump to 2-0-0. The reason for this is that there are possible schema instances which will validate against the 1-0-0 schema which cannot validate against the 2-0-0 (because the 2-0-0 is much more prescriptive - a good thing). So a 1-0-x bump would be very misleading.

Does that make sense?

Thanks for the answer Alex,
the problem is the additional properties: true, right?

If I had, for example, the case that additional properties: false and I would add a new property then I could just bump to 1-0-1?

Hi @julianDii,

Yes, exactly. Problem is in additionalProperties. It can be tricky and we recommend to stick with false by default, especially if you control source of data.

For new property you will have to bump version in ADDITION (e.g. 1-0-1) if that new property is optional. Otherwise, if new property is required - this is again MODEL bump (2-0-0) because all historical data will be invalid against new schema (field is required) and all new data will be invalid against previous schema (previous schema explicitly stated there’s no such property), so they’re backward and forward incompatible.

1 Like

Thanks Anton for the precise explanation,

I did the mistake to set up all my initial schemas with additionalProperties:true. :slight_smile: