Define unified versioning system for machine and human readable definitions.

[OR13]

The registry is append only... so we don't need to worry about definitions being removed.... we do need to worry about making it clear what versions support what definitions, and the structure for storing definitions... I suggest the following:

/contexts/v1/did-v1.jsonld
/schemas/v1/didDocument.json (with the schema version encoded in the $id)

https://www.w3.org/ns/did/v1 = > /contexts/v1/did-v1.jsonld
??? => /schemas/v1/didDocument.json

Note that v1 is UNSTABLE... so PRs modifying it should not be blocked by concerns over adding new items to an existing defintion file.

https://www.w3.org/ns/did/v0.11 = > /contexts/v1/did-v0.11.jsonld
??? => /schemas/v0.11/didDocument.json

Note that v0.11 is STABLE... so there should never (EVER) be changes make to these files... since we never had json schema for v0.11, I am happy to add support for it as we define properties in v1... if we get to the end, and there are properties defined in v0.11 that have not been added to the did-core-registry, we will need to decide what to do about that... simple solution is to do nothing... and mark them as not allowed.

[iherman]

https://www.w3.org/ns/did/v1 = > /contexts/v1/did-v1.jsonld
??? => /schemas/v1/didDocument.json

The https://www.w3.org/ns/ space is not reserved for JSON-LD purposes; it can, and is, used for other types of similar things (e.g., xml namespace documents...). I would be in favor of using the same URL area (with some naming scheme) for the json schemas as well.

Actually, the current set up is based on a var file:

8:55 did> ls
v1.var
8:55 did> more v1.var
URI: v1

URI: v1.jsonld
Content-Type: application/ld+json; qs=0.5

URI: v1.json
Content-Type: application/json; qs=0.4

8:55 did>

And there is a draft media type request for a application/schema+json. Would it be too risky to add this to the var file and let content negotiation win? Ie, https://www.w3.org/ns/did/v1 be used for both the json ld and the json schema, and the right media type in the HTTP request header would decide?

(I am not sure that the various tools are really well prepared for that, though. We may want to stay away from that, but I thought I would ask:-)

[OR13]

I'd prefer to get it working without content negotiation first, and I worry about the usability of the files if I need to open up an HTTP header tool to browse them...

I would want to be able to use a normal web browser and follow hyperlinks for:

https://www.w3.org/ns/did/v1 => human readable
https://www.w3.org/ns/did/v1/jsonld => jsonld
https://www.w3.org/ns/did/v1/json => json schema

in the long run I wouldn't be opposed to content negotiation.... especially if the human readable documentation has direct pointer to the ns files in github.... but if the human readable documentation is super disconnected from the machine side (as is the case today), and its super hard to figure out where to go to review the terms, and where to go to fix them... I would really not like the content negotiation, as it adds another layer of indirection...

[selfissued]

I agree with @OR13 that the human-readable registry representations should be viewable as a Web page. Bonus points for having the JSON Schema be viewable as JSON in browsers that support it, such as Firefox.

[iherman]

Technically, #17 (comment) is perfectly doable, and I agree with @OR13 that it is a neat solution. It is actually in line with what is usually preferred for, say, RDF vocabularies that may have a version of the vocabulary in Turtle, in JSON-LD, in (don't shout at me:-) RDF/XML, but with the 'core' reference going to an HTML file.

[iherman]

@selfissued the schema file should be served as application/schema+json. This means that browser like Firefox would recognize it, at the minimum, as json, and it would then display as you suggest. The same would hold for the jsonld part. I believe we get that for free.

[rhiaro]

I'd prefer to get it working without content negotiation first

In my experience of w3c namespace hosting with conneg, sticking the file extension on the end actually renders the version you want to see in the browser.

Eg. https://www.w3.org/ns/activitystreams defaults to a human-readable (HTML) version of the terms (or at least, the browser sends an Accept header for HTML and gets it back), and conneg works for serving the JSON-LD context when requested, plus https://www.w3.org/ns/activitystreams.jsonld lets you go straight to the JSON-LD without sending an Accept header.

This means we can have a single URL for all versions (because browsers/libraries/software should be sending Accept headers for what they want) and still have a shortcut to get to specific syntaxes as humans for debugging purposes.

I'm opposed to minting several different URLs for different representations of the same content.

[OR13]

thats awesome ^ can we get that setup for /ns/did asap?

[msporny]

thats awesome ^ can we get that setup for /ns/did asap?

This would be a question/request for @iherman, @brentzundel, and @burnburn:

At present, the DID namespace doesn't resolve/redirect to the DID Core Registries HTML file when "Accept: text/html" is provided:

https://www.w3.org/ns/did

Can we make it do that now, or do we need to wait until the WG signs off on a FPWD for DID Core Registry?

[iherman]

https://www.w3.org/ns/did

Can we make it do that now, or do we need to wait until the WG signs off on a FPWD for DID Core Registry?

Just to be precise: I presume you mean https://www.w3.org/ns/did/v1, right? (at the moment, e.g., https://www.w3.org/ns/did/v1.jsonld does redirect to the github file but https://www.w3.org/ns/did/ does not).

As for doing it now: I do not have a preference; we are already redirecting the jsonld versions to the github repo file.

However, we should have a clear setup.

• Where should https://www.w3.org/ns/v1 redirect if no media type is required? Should it be a 404? (My feeling it should go to the HTML file)
• Where should https://www.w3.org/ns/v1.json go? At present, it goes to the JSON-LD context; after the changes it may have to go to... a schema file? What else?
• There is no preferred suffix in schema media type request, so how would we incorporate that into the scheme?

I must also say I am bothered by the fact that schema media type request is now noted as "expired" (it expired on the 19th of March), which may be a sign of the unstable nature of json schemas...

[msporny]

I presume you mean https://www.w3.org/ns/did/v1, right?

No, definitely not... :) -- I mean https://www.w3.org/ns/did

We haven't decided what happens when you request "text/html" for https://www.w3.org/ns/v1 -- you typically can only get JSON-LD for that resource (by design).

Where should https://www.w3.org/ns/did/v1 redirect if no media type is required? Should it be a 404? (My feeling it should go to the HTML file)

You should get the JSON-LD Context, always.

Where should https://www.w3.org/ns/v1.json go? At present, it goes to the JSON-LD context; after the changes it may have to go to... a schema file? What else?

It should go to the JSON-LD Context, always.

There is no preferred suffix in schema media type request, so how would we incorporate that into the scheme?

We don't, JSON Schema has always been and continues to be underspecified and rapidly changing... it's why lots of specs don't depend on it in any sort of normative fashion. We should remember that the JSON-LD Context and JSON Schema files are non-normative and should stay that way in order for us to be able to rapidly change them if necessary (security vulnerabilities, breaking changes to JSON Schema, and other things that happen at a more rapid rate than W3C RECs).

[burnburn]

31 March Call: Machine- and human-readable portion of this issue is addressed by Amy's proposal. Manu will comment on the remaining portion.

[iherman]

(from 31 March Call)

There's a slightly more general question: If everything is only JSON-LD then everything is fine and easy. The problem is that the HTML5 referred to is for all, i.e., JSON-LD and JSON and CBOR. If we have a redirection scheme then we should get something that's useful for all formats, and I am not sure what they are.

(JSON Schemas are unstable:-(

[rhiaro]

I want to clarify exactly what we're discussing the versioning of.

1. Is it the DID Core Registries landing page? That includes extension terms for properties, parameters, and eventually methods. Is the intent to increment the version of this whenever any extension is added? I believe it is planned to be a NOTE, which perhaps complicates things further - once the WG ends I think the NOTE should only be updated for errata etc, so I'm not sure how this works for a registry like this. While the work on the NOTE is ongoing, it is 'versioned' through the chain of published WDs like all W3C documents.

2. Is it the JSON-LD context? I think we already have versioning with the /v1 etc in the URL, no? And once the DID Core Spec is finished, there's no place for updates to v1 of the JSON-LD context, because it should be frozen by then, right?

[OR13]

PROPOSOAL:

The registries are append only, so we don't need to version the html.

JSON-LD, CBOR, JSON Schema, will all have an unstable version, and stable versions, separated by directory.

https://example.com/ns/did-core-registries/index.html

https://example.com/ns/did-core-registries/v1/jsonld/did-v1.jsonld
https://example.com/ns/did-core-registries/v1/json-schema/didDocument.json
https://example.com/ns/did-core-registries/v1/cbor
...
https://example.com/ns/did-core-registries/v2/jsonld/did-v2.jsonld
https://example.com/ns/did-core-registries/v2/json-schema//didDocument.json
https://example.com/ns/did-core-registries/v2/cbor

JSON-LD may rely on only a single context file.
JSON Schema may rely on multple files, linked together.
CBOR ... who knows....

[rhiaro]

Do you anticipate the unstable versions to still be needed after the spec is finalised? (Maybe we don't know yet - could depend if there's a maintenance WG.)

Bikeshedding URLs:

• jsonld context doesn't need the version number in twice does it?
• why do the json schema and jsonld contexts have completely different filenames?
• didDocument.json sort of seems like it would be a DID document. (But if that's normal sort of naming patterns for json schemas, ignore me)

The actual namespace for RDF purposes for the JSON-LD terms will still be https://www.w3.org/ns/did/v1 right? (<- this is a question for @msporny I think)

[OR13]

• why do the json schema and jsonld contexts have completely different filenames?

json schema has many files... json-ld has 1, json-ld defined vocabulary that is both inside and related to a did document... the way this is handled in json schema is not really defined, but it will likely be separated by files.

• didDocument.json sort of seems like it would be a DID document. (But if that's normal sort of naming patterns for json schemas, ignore me)

its sorta common for the schema name to match the Class or Type... but it's not a requirement.

I do think we need to account for updates to the registry... forever.

[rhiaro]

Point taken on json schema stuff, I'll butt out of that :)

I do think we need to account for updates to the registry... forever.

Updates to the registry, sure - this is how extensions are added.

Updates to the json-ld context and json schema for DID Core, no. Extensions don't get added to the core context/schema, but come with their own. The json-ld context and json schema will not be updated (apart from errata) once the spec is a REC. If there's a new version of the spec, there should be new versions of the context and schema. If there's a maintenance WG or some other group that is going to make changes to the core json-ld context, without Core Spec updates, this is gonna be a whole thing we have to discuss..

[OR13]

We figured this out as well as we can, see the examples in the test suite: https://github.com/w3c/did-test-suite

this issue should be closed.

[brentzundel]

As discussed on the call 7-27, this has been done

[iherman]

The issue was discussed in a meeting on 2021-07-27

• no resolutions were taken

View the transcript

3.3. Define unified versioning system for machine and human readable definitions. (issue did-spec-registries#17)

See github issue did-spec-registries#17.

Orie Steele: We did this, but the DID core test suite, if you look at context examples, there is community consensus on how to version contexts wrt. DID Documents including DID Core context.... and then there are community ones, date stamped, versioned... I think we should close this issue and point to examples in DID Core test suite.

Manu Sporny: +1 to close