Define compatibility policy

[rdb]

We should have decided on a compatibility policy by the time we release 1.0.0, and set up a regression testing system to enforce it. Will a SB 1.0.1 file be valid against the 1.0.0 spec, and vice versa?

Particular consideration needs to be given to the fact that “additionalProperties” is set to false in most places, indicating that fields unrecognized by the spec are disallowed rather than silently ignored, but this may also have to be revised depending on what we decide here.

[mvahowe]

I think it's hard if not impossible to define a compatibility policy without some agreement on possible processing models. For example, even adding an extra enum value can be breaking if the processor has one branch per known enum value and no "otherwise" clause.

[mvahowe]

Also, some of this comes down to how the schema works. If there's something to the effect of

version="1.0.0"

in a schema, any version change is automatically a breaking change. If that's not what we want, do we have a way to do "proper" semantic version parsing within our schema language?

[rdb]

I think it's hard if not impossible to define a compatibility policy without some agreement on possible processing models.

I agree, or at the very least, we would need some guidelines on how to parse the file, such as, "you must silently ignore unknown properties".

do we have a way to do "proper" semantic version parsing within our schema language?

One way to do this is to be more flexible about parsing the version (ie. schema 1.0.x will read 1.0.y for any value of x >= y, or something). Another way to do this is by referencing the schema by URL, so that the reader would be required to fetch a schema from that URL, but I don't think that approach has my preference.

[rdb]

We agreed that schema 1.0.x will be able to validate 1.0.y for any value of x >= y.

[jag3773]

Needs documented in:

• [x] Conventions section
• [ ] version section in schema

For example, 1.1.x is a whole new schema and will not validate 1.0.x.

Possibly allow x- prefixed fields or allow new key value pairs in an extensions/extras section?

[rdb]

For possible inspiration regarding the extensions/extras ideas, the glTF 2.0 format (a 3-D model format based on JSON) provides both a named extensions system and a container for arbitrary key-value pairs: https://github.com/KhronosGroup/glTF/tree/master/specification/2.0#extension The extra key-value system looks something like this:

{
    "extras": {
        "custom": 1,
        "noSemanticMeaning": "definedBySpecification"
    }
}

The extension system is less ad-hoc, made for stuff that is meant to be validated (using a schema for each extension). The file indicates which extensions a reader must support to be able to read the file:

{
    "extensionsRequired": ["VENDOR_extension"],
    "extensions": {
        "VENDOR_extension": {
            "these": "fields are validated",
            "using": "a vendor provided schema"
        }
    }
}

I don't really feel a strong impulse to go for any of this--it is something we could always consider adding later if the need for something like this becomes evident, otherwise this may end up being a solution looking for a problem.