Data Model Vocabulary versioning questions

[iherman]

In agreement with @msporny I will maintain the formal VC Vocabulary definition document. Apart from cosmetic changes, this means handling possible bugs like #770, but also adapting it to the v2 version of the model.

There is a practical versioning issue, though, which may need a consensus before moving on. The VC Vocabulary definition has never been published as a W3C Note. That means that the current (ie, dated 26 May 2019) is the only existing version of that document. If I go ahead and make any change whatsoever, history will be lost. The change we would do on the vocabulary definition will lead to a 2nd version of the vocabulary, that may or may not be 100% backward compatible. But I am hesitant to make any change that would indeed lead to a loss of history.

I would therefore propose that would make a "fork" (not necessarily a github fork) of the vocabulary definition. This can take two forms:

1. I make a separate folder in our vc-data-model repo vocab/credential2.0, make all the changes there and leave the current document intact. The new URL for the vocabulary will become https://w3c.github.io/vc-data-model/vocab/credentials2.0/credentials.html
2. I create a separate github repo, vc-data-model-vocab and move all the documents there. The new URL for the vocabulary will become https://w3c.github.io/vc-data-model-vocab. This may make it easier to publish, if the WG so decides at some point in the future, a bona fide WG Note for the vocabulary; but even without that decision it may avoid minor conflicts with the development of the main data model.

I am (though mildly) in favour of the second alternative.

Note that, as it came up in an discussion on the thread, this WG may want to take over the https://w3c-ccg.github.io/security-vocab/ as well to update and refresh. Whatever we decide here may have an effect on that decision, too, if we want to be consistent...

cc @msporny

[iherman]

A third option may be to create indeed a new repository, but called "vc-vocabularies" to contain and maintain all RDF vocabularies in one place.

[iherman]

Looking at the discussion in #905 (comment), and to be consistent with the way the v2 of the context file is handled, I decided to create a vocab/credentials/v2 and put the new version there.

Ideally, the current content of the vocab/credentials should be moved into vocab/credentials/v1 but that would require redefining the current redirections, and set up new ones. Can do this if we want to, but it may not be worth it.

[msporny]

In agreement with @msporny I will maintain the formal VC Vocabulary definition document.

Thank you!!! :)

Apart from cosmetic changes, this means handling possible bugs like #770, but also adapting it to the v2 version of the model.

+1

There is a practical versioning issue, though, which may need a consensus before moving on. The VC Vocabulary definition has never been published as a W3C Note. That means that the current (ie, dated 26 May 2019) is the only existing version of that document. If I go ahead and make any change whatsoever, history will be lost. The change we would do on the vocabulary definition will lead to a 2nd version of the vocabulary, that may or may not be 100% backward compatible. But I am hesitant to make any change that would indeed lead to a loss of history.

Hrm, I'm probably misunderstanding what you're saying... we have history on the vocabulary here:

https://github.com/w3c/vc-data-model/commits/34b9b9224f74a49206cebef44977cee7f5087dec/vocab/vocab.csv?browsing_rename_history=true&new_path=vocab/credentials/vocab.csv&original_branch=main

1. I make a separate folder in our vc-data-model repo vocab/credential2.0, make all the changes there and leave the current document intact. The new URL for the vocabulary will become https://w3c.github.io/vc-data-model/vocab/credentials2.0/credentials.html

Hrm, would https://www.w3.org/2018/credentials/ serve up the content from https://w3c.github.io/vc-data-model/vocab/credentials2.0/credentials.html ? Or would it redirect?

We should probably publish the credentials vocabulary as a NOTE and serve it from https://www.w3.org/2018/credentials/ ... because the base URL for a good chunk of VC terms right now is https://www.w3.org/2018/credentials#.

2. I create a separate github repo, vc-data-model-vocab and move all the documents there. The new URL for the vocabulary will become https://w3c.github.io/vc-data-model-vocab. This may make it easier to publish, if the WG so decides at some point in the future, a bona fide WG Note for the vocabulary; but even without that decision it may avoid minor conflicts with the development of the main data model.

The problem here, of course, is that the vocabulary is supposed to reflect the contents of the specification. By separating them from one another, we increase the risk that they get out of sync. We also make it harder to understand why changes were made to the vocabulary, editors will have to remember to actively cross-link actions and that introduces human error into the mix. I think I'm a -1 to this approach because it also applies to the JSON-LD Context -- should we move that out into a separate repo as well? The counter-proposal is to keep all of this stuff together if we can so it is easier to manage changes across the VCDM, JSON-LD Context, and vocabulary at the same time.

A third option may be to create indeed a new repository, but called "vc-vocabularies" to contain and maintain all RDF vocabularies in one place.

-1 to this, it'll be difficult to categorize something as a "VC" vocabulary. Are the DI vocabularies "VC vocabularies" -- definitely not. Should extension vocabularies go into "vc-vocabularies", or should they live with the extension that created them (I suggest the latter).

I decided to create a vocab/credentials/v2 and put the new version there.

Hrm, this makes it seem like there are now two vocabularies... something that we really, really want to avoid, IMHO.

Note that, as it came up in an discussion on the thread, this WG may want to take over the https://w3c-ccg.github.io/security-vocab/ as well to update and refresh. Whatever we decide here may have an effect on that decision, too, if we want to be consistent.

I expect we'd pull the security vocab into the DI repo. So the consistent rule would be -- JSON-LD Contexts and RDF Vocabularies go with the specification that establishes their existence and/or largely drives their modifications.

WDYT?

[iherman]

@msporny,

In some sense, #905 made some parts of the discussion obsolete, so I will skip over the part of creating a separate github repository. (I got to a similar conclusion as you...)

Hrm, I'm probably misunderstanding what you're saying... we have history on the vocabulary here:

https://github.com/w3c/vc-data-model/commits/34b9b9224f74a49206cebef44977cee7f5087dec/vocab/vocab.csv?browsing_rename_history=true&new_path=vocab/credentials/vocab.csv&original_branch=main

Right, and the same hold for the other files, but it really takes two PhD-s from github academy to really really use that; it is not comparable to the way the specifications have their history on W3C's /TR... I think we should make something more humanly usable:-)

Hrm, would https://www.w3.org/2018/credentials/ serve up the content from https://w3c.github.io/vc-data-model/vocab/credentials2.0/credentials.html ? Or would it redirect?

We should probably publish the credentials vocabulary as a NOTE and serve it from https://www.w3.org/2018/credentials/ ... because the base URL for a good chunk of VC terms right now is https://www.w3.org/2018/credentials#.

This is exactly the same situation as the context file. At the moment, we define v2 and, at some point, we will declare v2 as the new kid on the block. What I propose, in effect, is to do the same with the vocabularies: maintain a separate v2 for now, and when we feel like they are final, flip whatever we want to flip. I guess at that point some of our redirections will flip and yes, the .../credentials will lead to the new version. (Isn't that what you said in #905 (comment)?)

One of the reasons to keep it apart is because you do not want to change things for something evolving for implementers...

I decided to create a vocab/credentials/v2 and put the new version there.

Hrm, this makes it seem like there are now two vocabularies... something that we really, really want to avoid, IMHO.

Again, this mirrors the situation with the contexts... If the PR in #920 simply replaced the current vocabulary definition, a discrepancy would be created between the v2 context and its vocabulary. Not good either.

I expect we'd pull the security vocab into the DI repo. So the consistent rule would be -- JSON-LD Contexts and RDF Vocabularies go with the specification that establishes their existence and/or largely drives their modifications.

Ok. Deal.