The did-core registry MUST be machine and human readable.

[OR13]

A machine readable version of the registry will facilitate interoperability via software tests.

Lets postpone the choice about which machine readable formats should be supported...

Spec compliance must be testable. You can't easily test conformance with xhtml or text... the process of verifying JOSE implementations is tedious and involves things like: https://tools.ietf.org/html/rfc7520

The first thing an implementer does is convert these examples to structured data that can be imported into a test suite.

https://github.com/panva/jose/blob/4460c4c88f106878a9c56575a3a69c7eea35fccc/test/cookbook/recipes/4_8.multiple_signatures.js

https://tools.ietf.org/html/rfc7520#section-3.3

In a world where we published JSON Schema & JSON-LD, definitions for the core registry, you could pass a document in the appropriate representation, and instantly know if it was core compliant, linked data, or extended...

With all the property definitions also being human readable via an xhtml or text version derived from the machine readable one.

interoperability compliance should be testable, we should make it as easy as possible by using a machine readable format for the did core registry, and generate the human readable documentation from it.

If you are opposed to a machine readable registry with human documentation generated from it, please state your company name, along with an argument against supporting both machine and human readability for the core registry.

[msporny]

Interoperability compliance should be testable, we should make it as easy as possible by using a machine readable format for the did core registry, and generate the human readable documentation from it.

+1, this proposal makes loads of sense.

[selfissued]

It's not clear to me that a machine-readable registry is any more necessary than a machine-readable version of the DID Core spec. In both cases, it's programmers who are the audience of the specifications that they reference and it's programmers who write code to implement and conform to the specified behaviors, whether they're specified in the core spec or specs referenced from registries established in the core spec.

Don't get me wrong, I'm not philosophically opposed to machine-readable data formats, but I'd want to understand why they're necessary before deciding to also have them. The human-readable registries at the IETF have worked very well in practice, as one useful data point.

That said, I understand that machine-readable registries would let you test some syntactic properties, but wouldn't help you test semantic properties. For instance, a machine-readable version of the JOSE algorithms registry at https://www.iana.org/assignments/jose/jose.xhtml could help you check the syntax of JWS, JWE, and JWT objects, but wouldn't help you test whether signing, hashing, and encryption follow the specifications referenced from the registry. For that, you need test code that understands the required semantics when using the registry values - not just their syntax. To get the semantics right, you're still going to always read the specs referenced from the registries and implement them correctly.

To help everyone understand my background that informs some of what I'm saying, I am one of the people who created and run the OpenID Certification program https://openid.net/certification/, which has over 100 certified implementations. I'm 100% for interoperability and conformance testing, and have a lot of experience with it. That matters for achieving real interoperability a great deal. As we discussed at last week's F2F WG meeting, we'll eventually want to have interop tests and certification become a normal and ubiquitous part of the DID ecosystem.

[OR13]

As we discussed at last week's F2F WG meeting, we'll eventually want to have interop tests and certification become a normal and ubiquitous part of the DID ecosystem.

We have tests for all did methods in the universal resolver that want to use JSON-LD today... https://travis-ci.org/decentralized-identity/context/jobs/647116281#L279

For instance, a machine-readable version of the JOSE algorithms registry at https://www.iana.org/assignments/jose/jose.xhtml could help you check the syntax of JWS, JWE, and JWT objects, but wouldn't help you test whether signing, hashing, and encryption follow the specifications referenced from the registry.

If https://tools.ietf.org/html/rfc7520 was machine readable and included in that registry, you could use that single registry to also test whether signing, hashing, and encryption follow the specifications referenced from the registry.... of course to know if the implementations are safe to use is another matter... https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/

To get the semantics right, you're still going to always read the specs referenced from the registries and implement them correctly.

100% agree. For example, the current set of tests I shared above are failing for a number of cases. In one case, Microsoft engineers added a property to sidetree methods without documenting it. We fixed this issue, by documenting the property and including it in the DIF Context.

Without the interoperability tests for JSON-LD how would they have known they were creating a breaking issue for JSON-LD documents (other than reading the spec)? Without the documentation for the property, how would anyone know what they meant when they added "usage" to public key objects? Why didn't they consider adding it to the did core spec, or describing its relation to https://www.iana.org/assignments/jose/jose.xhtml#web-key-use ?

I'd like to be able to test a did document for did-core registry conformance, I can actually do that today with JSON-LD... as demonstrated above... It supports both human and machine readable formats. If we are going to create a new registry it must be at least this good... I'm in favor of making it significantly better.

Are you or Microsoft, formally opposed to defining the registry for did core in a machine readable format and generating the human readable documentation from it?

If the answer isn't yes or know, what kind of information would be needed to get to a yes or no? If you only care about the human readable version... you get that from my proposal :)

[msporny]

I'm wondering if we're just talking past each other. The WG had consensus on the following at the recent F2F:

https://www.w3.org/2019/did-wg/Meetings/Minutes/2020-01-30-did#section2-5

More specifically:

Extension authors must provide references to specifications for new entries and a valid JSON-LD Context to be associated with each entry to ensure lossless conversion between serializations for both producers and consumers. This is partly being done to ensure semantic interoperability.

JSON-LD is not optional wrt. registry entries -- you have to provide it w/ all registry entries -- as a result, you get a human-readable and machine-readable version, which is what @OR13 is asking for.

In theory, we should be able to automatically build the registry from the list of JSON-LD contexts... one could even go as far as asserting that you could build the registry entirely from metadata in JSON-LD Contexts. Remember that the JSON-LD Context files can contain machine-readable descriptions for the vocabulary terms that they use... you can embed an entire RDF ontology in a JSON-LD context if you so choose... which I'd probably argue against... would probably be a bridge too far. We may, instead, just want to use a CSV file to include descriptive text for the registry and autogenerate the human-readable version of the registry and double-check it against the JSON-LD Contexts, throwing an error if a JSON-LD Context contains something that's not in the registry or vice versa.

Any way you slice it, we agreed to having a machine-readable way of generating the human-readable registry if we want to do that.

[talltree]

I am generally in favor of the DID Extension Registry being machine-readable, for all the reasons @OR13 mentions. However I also agree with @selfissued that machine-readability will only get us so far in terms of interop. Getting the semantics right, and then testing interop complete with cryptosuite implementations, is what will get us (as an industry) the rest of the way there.

[OR13]

Example of machine readable registry for both JSON Schema and JSON-LD:

Human Readable:
https://identity.foundation/context/did-latest#usage
Machine Readable JSON-LD:
https://github.com/decentralized-identity/context/blob/master/did-latest.jsonld#L7
Machine Readable JSON-Schema:
https://github.com/decentralized-identity/context/blob/master/schemas/key.json#L37

Note the linkage between JSON-Schema and JSON-LD in the description annotation.

Rendered version of the tests: https://identity.foundation/context/test-report.html

[OR13]

blocked by w3c/did-extensions#3

[OR13]

We have this setup in did core registries, I would like to close this issue.

[brentzundel]

no objections raised since pending close label added. Closing.