DID Core Registries -> DID Extension Registries, plus clear inclusion of terms from Core

[rhiaro]

The DID Registries are primarily to coordinate interop between extensions to the DID Core Spec. That is, to facilitate implementers to do things we didn't specify in DID Core v1. To make this abundantly clear, I propose we rename the DID Core Registries to the DID Extensions Registries.

Of course it is useful to have all terms in one place, rather than two different documents for implementers to have to look at to get an overview of all the available properties (and params). To that end, we can have sections in the Registries document that lists the properties and parameters that are defined in the DID Core Spec, with links out. These should be clearly differentiated from the extensions, as they will have been defined by WG consensus under W3C process rigour, rather than by third parties who followed the registration process.

Something like the following structure for the Registries document:

1. Introduction
2. The Extension Registration Process
3. The Core Properties
4. The Core Parameters
5. The Properties Extension Registry
6. The Parameters Extension Registry
7. (The DID Methods Registry)

The repository for the DID Extensions Registries should contain:

• Human-readable (HTML) overview of process and registry entries (per structure above)
• DID Core JSON-LD context(s - multiple versions)
• Simple HTML view on the terms in the Core JSON-LD context(s)
• DID Core JSON Schema definition(s)
• Simple HTML view on the Core JSON Schema definition(s) (if this is appropriate and normal in JSON Schema land).

The various URLs should work thus:

• https://www.w3.org/ns/did returns the human-readable (HTML) Registries document, always.
• https://www.w3.org/ns/did/v1 returns a human-readable (HTML) simple listing of the contents of the JSON-LD context (core only, no extensions), if you ask for HTML, otherwise it returns the JSON-LD context, always.
• https://www.w3.org/ns/did/v1.jsonld and https://www.w3.org/ns/did/v1.json return the JSON-LD context, always.
• https://www.w3.org/ns/did/v1/schema returns a human-readable (HTML) simple listing of the contents of the JSON Schema if you ask for HTML, otherwise it returns the JSON Schema definition, always. (I'm just floating this, JSON Schema best practices a bit out of my wheelhouse.)

With the understanding that the ultimate goal (even if we're not quite there yet) is the following:

• every property in the DID Core Specification appears in the JSON-LD context at https://www.w3.org/ns/did/v1
• every term in the JSON-LD context at https://www.w3.org/ns/did/v1 is normatively defined in the DID Core Specification
• every term in JSON-LD context at https://www.w3.org/ns/did/v1 is listed in the Core Properties section in the Registries document, with links to the normative definitions in the DID Core Specification (for ease of navigation for implementers - not as a normative reference)
• every property not defined in the DID Core Specification but nonetheless in use by implementers who wish to interoperate, goes through the registration process in order to be listed in the Property Registry
• every property listed in the Property Registry links out to its normative specification (hosted anywhere) for a human-readable definition, JSON-LD context and JSON Schema definitions, as submitted during the registration process.

(This issue has overlap with #17).

[selfissued]

I disagree with the renaming. Core features, including the top-level JSON member names and method names, will be listed in the registries.

[msporny]

I expect that we may end up with "DID Registries" instead... because "core" is being misinterpreted as "only core", and "extensions" is being misinterpreted as "only extensions". We'll need more feedback from the group in order to go one way or the other (or neither).

[rhiaro]

Core features, including the top-level JSON member names and method names, will be listed in the registries.

I guess I don't understand why core features need to be 'registered' as they are specified, though I support listing them for implementer convenience.

I'd be fine with DID Registries though. I think DID Core Registries is confusing.

[rhiaro]

We'd definitely have to rename DID Registry, the term we have been using for the ledger/network/system/database that DIDs are actually recorded to... (in progress in w3c/did#162)

[rhiaro]

I missed a thought about what https://www.w3.org/TR/did-{shortname}-registries returns and how that differs (or not) from what ns/did returns. Still pondering.

[talltree]

With @rhiaro 's renaming of the issue, I very much like the structure Amy is proposing. Nice job.

[selfissued]

I could either live with DID Registries or DID Core Registries but I cannot live with DID Extension Registries. The name DID Extension Registries makes it sound like core features won't be registered by they will be, so that there's a complete JSON schema for the core DID features in the registries.

This is just like that all the core JWT claims, such as "iss" and "sub" are in the IANA JWT Claims Registry at https://www.iana.org/assignments/jwt/ so the list is complete. This is the normal pattern.

All the JSON members defined by the DID spec will be in DID Registries, but they aren't part of extensions. (That's just like that all of them will also be in JSON-LD Context files, even though they aren't extensions.)

For those reasons, "DID Extension Registries" would be highly misleading.

[talltree]

Since "DID Registries" strikes me as a confusing name (in fact a term we are trying to rid of any usage of in the DID Core spec), could a solution be to call it the "DID Core and Extension Registries".

[OR13]

If the name has "Core" in it, people will think it's only core properties (no extensions).
If the name has "Extensions" in it, people will assume it doesn't have core properties in it.

"DID Properties, Parameters, Extensions and Methods Registries"... is too long.
"DID Registries"... seems like the best bet.

[OR13]

@rhiaro can you provide example urls for the extensions as well?

Here is a real world example for extensions:

https://gpg.jsld.org/contexts/ (human readable)
https://gpg.jsld.org/contexts/lds-gpg2020-v0.0.jsonld (JSON-LD)

Assuming I provided json schema definitions for verificationMethods... how would I add them to the registries?

I open a pull request against https://www.w3.org/ns/did/index.html

• Add JSON-LD entries to https://www.w3.org/ns/did/extensions-v2.jsonld
• Add JSON-Schema files to https://www.w3.org/ns/did/did-extensions-v2/...
• Add HTML entries to the "Extensions Section"

Anyone wanting to use my public key definitions adds:

https://www.w3.org/ns/did/extensions-v2.jsonld to their @context ?

Every delta to the extension data results in a new version?

[rhiaro]

For those reasons, "DID Extension Registries" would be highly misleading. (@selfissued)

I'm clearly missing a perspective from the JSON/JSON schema, so I take your point about the problem with the name DID Extension Registries.

Since "DID Registries" strikes me as a confusing name (in fact a term we are trying to rid of any usage of in the DID Core spec), (@talltree)

My only objection to going with DID Registries is that we use DID Registry to mean something entirely different in the spec at the moment and we NEED to resolve that.

could a solution be to call it the "DID Core and Extension Registries". (@talltree)

Yes! Love it.

[rhiaro]

Assuming I provided json schema definitions for verificationMethods... how would I add them to the registries?

@OR13 I thought one of the agreements at the f2f, and how it is written in the Registration Process at the moment, was that every extension provides its own JSON-LD context and JSON Schema files. I tried to confirm this in #23. To me this means we do not host extensions in this repo at all. We just link out to where the implementer is hosting it, from the html landing page. We don't need schema or context files for extensions, because they're all elsewhere, nicely decentralised.

I open a pull request against https://www.w3.org/ns/did/index.html

• Add HTML entries to the "Extensions Section"

.. including the links to your (the extension implementer's) normative definition of the new term, and to where the JSON-LD context and JSON Schema are hosted, at URLs that you are committing to maintaining. And probably a hash of the context and schema, so the remote content can be verified.

Anyone wanting to use your extension adds your context to their @context. In the real-world example you've given, they'd add "gpgr": "https://gpg.jsld.org/contexts/#" to their context.

I'm not sure what you're asking about verificationMethods because verificationMethod (not plural) is already in the core context, so I assume it will be defined in the core spec, and therefore not an extension. If you do mean someone hypothetically wants to define the plural version of that term, then they'd write their own human-readable spec and context and schemas for it, and submit the URLs to these things to the registry in a PR, and anyone wanting to use them in JSON-LD would discover them through the registries and use the submitted namespace URI as defined in the submitted JSON-LD context definition.

The Registration Process is there to have some degree of quality control over extensions (according to the list of points in Registration Process); to make sure people commit to and properly maintain their extensions; and to give other people a place to look for existing extensions to use (before they go making their own). It is not a free hosting service for JSON files.

That's my understanding at least. I wasn't at the face to face, so I might have missed something crucial. But on subsequent calls where we were talking about the registries, I distinctly remember strong feelings about having the ability to host extensions elsewhere, not force them to be under the w3c namespace.

We could think about a special process for agreeing to host some extensions under certain conditions, if you think this is necessary or appropriate. I think this would need to be discussed separately. (For example, if one of the DID method specs were to be taken as a work item of the WG, and needs to define some new terms.)

[talltree]

If the name has "Core" in it, people will think it's only core properties (no extensions).
If the name has "Extensions" in it, people will assume it doesn't have core properties in it.

@OR13 That's exactly why I proposed "DID Core and Extensions Registry". It says in black and white that it has both Core and Extensions. What am I missing?

BTW, the problem with "DID Registries" is that it's easily confused with Verifiable Data Registries (assuming we settle on that term in the spec).

[rhiaro]

"DID Core and Extensions Registry". It says in black and white that it has both Core and Extensions.

Can't believe I didn't think of that tbh

[msporny]

"DID Core and Extensions Registry"

:( -- but it also has "Methods"... and "Parameters"... and everything else we haven't thought of yet. I suggest we name it "DID Registries" and fix whatever is broken in the spec.

[rhiaro]

:( -- but it also has "Methods"... and "Parameters"... and everything else we haven't thought of yet. I suggest we name it "DID Registries" and fix whatever is broken in the spec.

Doesn't extension and core also cover the methods and parameters? They'll either be core or extensions too, surely..?

[msporny]

Doesn't extension and core also cover the methods and parameters? They'll either be core or extensions too, surely..?

I'm merely pointing out that each time we've added a word, someone has gotten confused. :)

For example, a DID Method is neither an extension or in core.

[rhiaro]

For example, a DID Method is neither an extension or in core.

D'oh yes, that's true.

[OR13]

A side effect of this structure is that in order to create a valid "Extension" an implementer needs to support both "JSON Schema" and "JSON-LD"... I expect that nobody will actually contribute extensions because of this... given that we have yet to see anyone create a valid JSON-LD context extension, and now they will be required to do that AND create a valid JSON Schema... none the less, I will provide an example of such an extension...

[OR13]

I have attempted to reflect some off the structure which appears to have consensus here: #33

[rhiaro]

A side effect of this structure is that in order to create a valid "Extension" an implementer needs to support both "JSON Schema" and "JSON-LD"...

I thought that was precisely the compromise that was agreed at the face-to-face. That is also what it has said in the 'Registration Process' section all along.

[rhiaro]

When it comes to people adding extensions, I suggest we have a template for them to fill out when they make a PR. It could involve a table like:

Extension name	Authors	Specification	JSON-LD context	JSON schema
GpgVerificationKey2020	..	https://github.com/transmute-industries/lds-gpg2020	https://gpg.jsld.org/contexts/lds-gpg2020-v0.0.jsonld	...

Plus any additional notes/description, and an example usage.

[OR13]

yea, I feel like we are going to probably need to flatten the current registries to lists of tables, like this. I had hoped to have the registry provide some better guidance on structure, but i think that should be a another section. I will probably open a PR to flatten the current structure, after #33

[rhiaro]

Thinking more about naming; finding it hard to think of anything that clearly incorporates the Methods Registry without being overly general. In my head I'm calling it DID Stuff Registries.

DID Terms Registries? DID Spec Registries? DID Standard Registries?

[rhiaro]

Registries has had a name change and been restructured, I think this issue can be closed.