spec versioning

[grahamgower]

The spec will probably want a version number/string. I'd imagine we might want to start somewhere close to 1.0?

[jeromekelleher]

Agreed, we should start at 1.0 - we don't want to be changing much, and should be strictly semver about it.

[jeromekelleher]

Should the version key be a required key, or can we default it to 1.0? I guess if we error on any unknown fields (#28), then it's safe to have it as 1.0 by default. It's only if the demography JSON contains stuff unknown to 1.0 that the version key will be required (which seems OK).

[grahamgower]

Maybe we just need to reserve the keyword in the data model, and not provide a default at all? Implementations can ignore this field until there's a spec version > 1.0, it's just a clear signal to not use if for their extensions.

[jeromekelleher]

Why not default it to 1.0? I think we need to be clear about our plans for extensions the spec.

[grahamgower]

Ok, lets talk this through... Say we start with a default of 1.0, and we later release v1.1 of the spec. Does this mean the default version gets bumped too? Say the new spec includes a new parameter x somewhere. It's optional to specify the x and it has default of 0. Does not specifying the version mean we get spec v1.1 behaviour (x=0), or spec v1.0 behaviour (x undefined)? Do all files hereafter need to specify the version to get spec > 1.0 behaviour?

[jeromekelleher]

Do all files hereafter need to specify the version to get spec > 1.0 behaviour?

Yes, that would be my take. Version 1.0 is a fairly expressive minimum which we hope will be enough for the vast majority of use-cases. Therefore, making 1.0 the default gets rid of some annoying boilerplate. If someone wants to use features from 1.1 (which isn't supported in software using 1.0 parsers, by definition) then they need to specify schema_version=1.1 at the top.

Otherwise, I don't think we can avoid the problem of simulators silently dropping features from the model from newer schema versions.