[Policy Proposal] Versioning Resources

[mmccool]

Resources should be versioned and old resource files available at specific URLs. There can also be a URL to access the "latest" version. HTML files for ontologies, etc. should indicate the version and have a change log.
Even minor bug-fixes should be versioned, and the most specific link to a resource should refer to a "write-only" file that is guaranteed not to change.

Semantic versioning can be used, e.g. 1.0.1.

To discuss...

See also w3c/wot-discovery#535

[egekorkan]

Also see https://github.com/w3c/wot-thing-description/blob/main/VERSIONING.md. We need to be clear about whether this applies to 1.1 or 1.0 spec resources as well. Even though it can apply to them, there are issues with it:

• RECs do not mention a "resource publication", just saying here is a link for that resource.
• The RECs do not provide a meaning to different versions.
• Users of our specs do not expect multiple versions

I strongly think that we need this for 2.0 resources, even more strongly for bindings since they also have similar resources to our specs (ontology and schemas at least).

We also need to clarify if this policy includes such resources made public before a REC release. See the points under "Do we version anything until a REC release" in the link above.

[mmccool]

I will make an effort to join the TD call on Jan 25 to discuss - in the meantime let's collect input here.

[sebastiankb]

from today's WG planning session:

• @mmccool this topic will be discussed in tomorrow's TD binding meeting (slot 2 of the TD calls)
• @danielpeintner is this also cover schema files like JSON Schema and SHACL/SHAP files? --> needs to be clarified

[mmccool]

• Think it should cover all resources - including validation files, which have similar issues wrt caching, and need to be aligned with ontology files anyway (e.g. matching version numbers -> matching sets of files). Also documentation resources obviously have to be versioned to match the other resources they document.

[mmccool]

In the linked doc in TD the need for "beta" versions is noted. This is useful for testing (where we do need things available at specific URLs). I'd like to also suggest we have "release candidates", but we can also keep it simple and just have M.m.p.b where M, m, p are numbers (semantic versioning) and b is an optional letter (a,b,c, etc) for "testing" versions (and these are NOT referenced as the "latest", only the last "patch" version is referenced by the "generic" URLs.)

[mmccool]

Another constraint: to make the web master's job easier, the URL structure and the directory structure in the wot-resources repo should match, so we avoid having to maintain complicated mappings. The only redirection we may have to update is where the "generic" URLs point (unless we want duplicate files in the repo, although we could do that, it would be inelegant and subject to error).

[mmccool]

As for updating "old" files to use versioning: we need to keep the old URLs around for compatibility, but that leads to multiple URLs for the same thing, which makes them look like different entities to RDF. So I vote we DON'T do that, and just establish a mechanism "going forward" and avoid (except, maybe for versioned/generic URLs for the "latest" version - but see next point) different URLs for the same entity.

[mmccool]

We should investigate if there is a general mechanism for "synonyms" in RDF. The other option is to NOT have "generic" URLs and always have versions - URLs are hidden anyway by the context mechanism that defines prefixes. I think we can consider the prefixes to be the "generic" reference, then you could always include a "versioned" context URL, avoiding ambiguity and the synonym problem.

[egekorkan]

TD call of 25.01:

• Matching version numbers

  • @egekorkan: Matching the versions of files would mean that breaking changes in one file would increment the version in the other ones.
    • @mmccool : we can version the folder and let git show what file has changed between versions
    • @mahdanoura : Also, the deprecation of terms needs to be considered

• Changelog

  • @mahdanoura : we should communicate the reason for the change and what the change was. We also need to define what we mean by major, minor, and patch.
  • @mmccool : Discovery TF did a changelog "test".
  • @relu91 : commit messages to drive the changelog. There are tools for that but may not work for "documents". We need to define guidelines as well, e.g. using "chore" when doing a small fix.
  • @mmccool : we should let git/GitHub do the work for us, if possible. Tagging etc.
  • @mjkoster : docstrings in commit messages can be used to automate changelog

• Who is targeted by which change:

  • @relu91 : There are Developers who try out the specs so there is no version "just for us".

• @egekorkan : Maybe there are options other than manually updating specific files and redirection.

Overall comments:

• Best practices for RDF versioning should be studied. See https://www.w3.org/TR/prov-primer/

What do we want to achieve by versioning:

• We should write a user story from the Consumer or Exposer of TD point of view.

Next steps:

• Move these comments + IRC minutes into a file. Next week Thursday we will continue discussion on this.
• Please write comments in this issue until Tuesday end of day.

[egekorkan]

I have copied the points above to w3c/wot-thing-description#1965

[mahdanoura]

There needs to be also some supplementary metadata that needs to be provided in versioned ontologies like dct:created, dct:modified, dct:valid, vann:changes, and the relation between the ontology versions. Also, I checked the OWL Language Reference document in Section 7.4 detailing ontology versioning. It states that the owl:versionInfo is an annotation property, owl:priorVersion, owl:backwardCompatibleWith and owl:incompatibleWith are ontology properties, where owl:Ontology is considered as the domain and range. Therefore, this shows that OWL requires different versions of an ontology to have different URIs.

[mahdanoura]

We should investigate if there is a general mechanism for "synonyms" in RDF. The other option is to NOT have "generic" URLs and always have versions - URLs are hidden anyway by the context mechanism that defines prefixes. I think we can consider the prefixes to be the "generic" reference, then you could always include a "versioned" context URL, avoiding ambiguity and the synonym problem.

According to OWL2 specification, for every ontology we can define an Ontology IRI (generic reference, should stay the same through versions) and a Ontology Version IRI. In particular, mentions:

Each ontology may have an ontology IRI, which is used to identify an ontology. If an ontology has an ontology IRI, the ontology may additionally have a version IRI, which is used to identify the version of the ontology.

The difference is during dereferencing of the IRIs, the ontology IRI should redirect to the most recent version and the version IRI to the specific version.

[mahdanoura]

There is also a proposed standard, MOD2.0 specification for describing ontology metada and semantic artifacts. It has some metadata we could reuse for our versioned ontologies.

[mmccool]

I think aligning our versioning with the OWL2 capabilities makes sense. We do have non-ontology resources but I think we should "group" version them consistently.

[mmccool]

Also, the use of a "generic" IRI (points to the latest "production" version - may need another generic IRI for "testing" versions, though) and "version" IRIs for specific version aligns with what I was thinking. Seems like "synonyms" are not a problem according to this, either.

[mmccool]

To support CBOR-LD, we need to "freeze" each version of ontologies. Some specs even go so far as to publishes SHA-256 hashes as part of specifications. This is necessary so assignment of numbers for fields in CBOR-LD is fixed. It also means that given the URL of a context, a device can assume it and "compile it in" rather than dereferencing it when reading the TD.

So for ontologies at least, we should not change ontologies at all when publishing them under a specific, even for "small" changes.

[sebastiankb]

just for understanding: Do we need to freeze each used ontologies within the TD context file or would it be enough just to freeze the TD context file and register https://www.w3.org/2022/wot/td/v1.1 at the CBOR-LD registry. I don't see any complications with the latter.