w3c
Explanation on the DID Methods in the registries' document
At present, §6 in the document is clearly different from the others. I presume the process described in §3 is not directly relevant for the methods, the table contains a column ("Status") whose meaning is not clear, and there is no more explanation. It is good to have this registry here, and I know it has a different origin to the other sections, but I believe it would need some urgent editorial care...
@iherman can you rephrase this as a directive for me or @msporny ?
happy to take a stab at a PR, if I can figure out what to do.
Let me try to be more specific.
- §3 describes the registration process. But that section is relevant for properties only. It does not seem to be relevant for parameters (ie, §5) and for DID methods (ie, §6). The process must be clearly defined for those two categories, too.
- The tables in §4 all have three headings: Normative definition, JSON-LD, and CBOR. It is not entirely clear from the description what the CBOR column means (it is relatively obvious that the second column refers to the relevant JSON-LD context).
- B.t.w., there are number of properties, like §4.4.1. and others, where what seems to be a reference to the JSON-LD context is under the CBOR heading; I guess that is a bug.
- The text should also make it clear how JSON comes into the picture. I presume it is simple, ie, the name used in JSON-LD is, verbatim, the key name for JSON as well, but this should be stated.
- In contrast to §6 there is no trace on the origin of the property or parameter: who submitted it and why? This is in contrast to methods, ie, §6.
- §6 uses a different structure. As I said, the registration process in §3 does not tell me how these are registered; ie, there is no explanation for what the 'Status' and 'Link' columns mean, and "DLT or Network" might not be clear for everyone. I presume the last column is a link to the description (this is equivalent to the 'normative definition' in the previous headers, right? Can we use the same terminology?). I would expect the description of the registration process to shed some lights on these.
- See my remark above on authors and the difference between §6 and the other sections.
- There is an editorial inconsistency. In §4 and §5 each submitted property has its own subsection, with a small table referring to the normative definition, the JSON-LD, and the CBOR references. §6 does not follow the same structure, it instead lumps all the methods into one giant table, without any example for usage (although it may not be clear what one would put there as an example). I am not sure which approach is better but, I must admit, this inconsistency bothers me.
I hope this helps.
As an aside, I wonder whether the registration process for DID methods should not be more demanding. I just glanced into some descriptions and, I must admit, I simply do not see what makes them interesting, useful, why they are there. In some cases the only information I really get is "it is a DID implementation on the XYZ blockchain". This is not very helpful. I believe we should require a 1-2 paragraph description for each of the methods that would describe why that DID method is interesting, unique in some way, etc.
@iherman I have tried to address some of your concerns here. https://github.com/w3c/did-spec-registries/pull/115/files
@iherman I have tried to address some of your concerns here. https://github.com/w3c/did-spec-registries/pull/115/files
Ack.
PR that addressed this issue was closed. Still need a PR for this. @peacekeeper will take a look
This was not resolved, the PR noted above wasn't ever merged. Some text might have made it into DID Core to address the issue.
The issue was discussed in a meeting on 2021-08-03
- no resolutions were taken
View the transcript
5.1. Explanation on the DID Methods in the registries' document (issue did-spec-registries#83)
See github issue did-spec-registries#83.
Brent Zundel: explanation on did methods in registries document, raised by ivan
Ivan Herman: more than a year ago
… the last comment is from orie saying i have tried to addressed, I acknowledged it.. seems like this issue should have been closed a long time ago
Manu Sporny: the PR, there was a massive permathread in it and it got closed, never went in
Ivan Herman: vaguely remember when I raised it registration of terms and methods and they looked different from one another but don't know what happened since then
Brent Zundel: The PR that tried to address the issue was closed rather than merged
Manu Sporny: this was orie and markus going back and forth over normative language in did core...
… my expectation is something got into did core and it was potentially resolved
Markus Sabadello: I can't check right now but will look later
I think some of this has been resolved (e.g. the CBOR column has been removed, and there is also some language now on how DID methods will get accepted into the table). But some other issues here are probably still open, e.g. about the structure and contents of the table.
A few weeks ago there was an idea that the "Status" field in the table could contain the value "tested" or "implemented", if an implementation of the DID method was submitted to the test suite.
Probably need to discuss this topic again on a WG call with @iherman who raised this issue, to see how much of it still needs to be addressed.
Related issue is https://github.com/w3c/did-spec-registries/issues/174, which also discusses tracking contact information for DID methods and other additions to the registry.
The issue was discussed in a meeting on 2021-09-14
- no resolutions were taken
View the transcript
7. Explanation on the DID Methods in the registries' document (issue did-spec-registries#83)
See github issue did-spec-registries#83.
Brent Zundel: issue has been around a while. DID method section has a status column. 99% says provisional for status.
… what do we want that column to say? Do we want to explain provisional, etc.?
Drummond Reed: Added a reference to where I had put another comment. Original suggestion was to create a new table that li-sts methods where authors have upgraded their methods to match the Recommendation.
… old table stays as is, but provisional changes to "upgraded" for such methods and people should look at new table.
… it will help us call out name squatting
… quality of the did method specs varies. This will leave us with methods that meet our now higher bar in the main table.
Joe Andrieu: worried about how you proposed it. Worried about new name squatting.
… we do need consensus on the legitimate values for status and how they're determined.
… when we first added provisional, it was to deal with methods that might not be consistent with current spec draft.
… need to figure out states, what they mean, and how they are assigned.
Ted Thibodeau Jr.: it seems that members of the new list should either be removed from the old (which is thus not static), or included on both with current status shown (and the old is again not static)
Ivan Herman: since we want this to become a formal registry, the doc itself has a registration process and that process says nothing about registering a new method. There is just a table, but no registration process. We need a clear policy for how things get into the table.
… we made a decision it would become a registry, but many details remain
Drummond Reed: Agreed, Ted. The proposal I made is that the only change to any methods listed in the Old table is that their status column value is changed if that method becomes listed in the New table.
Brent Zundel: we should use provisional (written before there was a spec), v1.0 compliant (submitted after the Recommendation), and deactivated (for no longer in use).
Justin Richer: what if the states are "Pre-1.0", "1.0", and "Deprecated"?
Justin Richer: basically what Brent Said
Justin Richer: or burn. Somebody said it.
Justin Richer: but basically call it "version" instead of "status" might help, too -- but that's a different argument
Ted Thibodeau Jr.: implementations submitted before DID Core 1.0 CR/PR could be listed as such, or de-listed for registry purposes
Drummond Reed: if we keep the current table, prefer what justin typed above
… no matter how we do it, need a clear policy on how to get the status changed.
Brent Zundel: next step should be a pull request proposing new language
Joe Andrieu: whoever the owner is of an entry, they should be able to self-assert which version of spec they claim to be compliant with
… since these will live for years and we need to plan for the future
Drummond Reed: +1 to being able to continuous upgrade the status values for future versions
Brent Zundel: any volunteers to write a PR?
Ryan Grant: I'll volunteer
Brent Zundel: reminder for Imp. Guide PR review and request for other PRs, we will keep you informed of the progress of the spec
… thanks for remaining professional.
@rxgrant and @jricher: at the end of the DID WG call last week, both of you had a specific suggestions for the values of the Status tag in the DID method table and the rules that the Registry editors should follow to assign those values. Could one of you submit a PR?
@rxgrant and @jricher: at the end of the DID WG call last week, both of you had a specific suggestions for the values of the Status tag in the DID method table and the rules that the Registry editors should follow to assign those values.
My read of the end of the conversation was that there was general approval to add a (blank) column to the table of DID Methods which would link to their updated-for-1.0 DID Method spec, that the (generally) "Status: PROVISIONAL" column should be removed, that old links should be labeled as pre-1.0 versions, and that since DID Method authors should self-certify, the registry should not attempt to declare their status. I will submit a pull request with these changes and briefly describe the change above the table.
As part of this work, I've reviewed all the existing DID Method Specifications and noticed that several do not resolve to existing web pages. I believe that #83, as it's currently scoped, does not cover editorial judgement on changing the status of these DID Methods, but point out that we need a process that has certain minimum standards.
Per a request from @OR13 in PR #341, and in light of the feedback received in the formal objections to the DID 1.0 spec, for the third time I will put forth the proposal that we split the DID method registry table into two tables:
- A new table for all v1.0-compliant methods (listed FIRST).
- The existing table for all current provisional registrations (listed SECOND).
Proposed rules for these two tables
- All new registrations MUST be v1.0-compliant and MUST go into the new table—the old table is locked.
- All existing registrants who submit a new v1.0-compliant version MUST be added to the new table and MUST be removed from the old table.
- Both tables SHOULD have the same set of columns:
- Method Name
- Status
- Spec Link
- Author Link(s)
- Verifiable Data Registry
- Status values for the old table:
- Provisional
- Deprecated
- Status values for the new table:
- v1.0-compliant
- In production
- Test suite available
- Approved standard
- Deprecated
Rationale
Besides giving greater visibility to v1.0-compliant DID method specifications, the two-table approach would enable us to put an explanatory paragraph before each table that should reduce confusion, not increase it.
The para before the first table can explain that these are DID method specifications submitted AFTER the DID 1.0 spec reached PR and that meet all the requirements of a compliant DID method.
The para before the second table can explain that these were all DID method specifications submitted prior to completion of the DID 1.0 spec, and thus are all provisional until they submit a v1.0-compliant DID method specification.
This way it becomes much easier for implementers to "separate the wheat from the chaff".
proposal that we split the DID method registry table into two tables
I'd be happy to implement this in the existing pull request. Any objections?
I'd be happy to implement this in the existing pull request. Any objections?
@rxgrant Not from me! I suggest we see if there are any objections or modifications on tomorrow's DID WG call. Then let's go for it.
The issue was discussed in a meeting on 2021-10-19
- no resolutions were taken
View the transcript
4.1. change registry columns per issue #83 (pr did-spec-registries#341)
Orie Steele: PR reviews: https://github.com/w3c/did-spec-registries/pull/341
See github pull request did-spec-registries#341.
See github issue did-spec-registries#83.
Daniel Burnett: framing questions: what's necessary to continue the work? can everything else work on github as issues?
Orie Steele: i want to thank ryan for an issue-first, PR-second approach that resolves many registry problems
… we haven't always been timely about the registry, so plz plz review those PRs, it helps us with many of our core issues as a WG
… i won't summarize ryan's very broad PR because it covers a lot of ground but review it soon, particularly if you have a did method that might get booted by its being merged!
Drummond Reed: i think this PR is urgent vis-a-vis the formal objections!
… I shared a link to an alternative solution opened in another issue
Manu Sporny: since we're on that issue (pr 341), my only suggestion is to replace "non-compliant" with "provisional"
… or rather, NOT to replace it-- we will look bad if we overnight switch most of our registry to "non-compliant"
Drummond Reed: +1 to not using "non-compliant". But https://github.com/w3c/did-spec-registries/issues/83 proposes a more comprehensive solution.
Ted Thibodeau Jr.: "experimental"?
Ted Thibodeau Jr.: "beta-compliant"?
Manu Sporny: replace "non-compliant" with "provisional" in the PR, i mean
Drummond Reed: +1 to "trolling the DID method spec authors"
Drummond Reed: Comment being discussed: https://github.com/w3c/did-spec-registries/issues/83#issuecomment-946075510
Ryan Grant: I was trolling, it's true, or put a little fire under them. I would support drummond's solution and I think it addresses manu's objection
Orie Steele: I will happily review a PR drummond, you are welcome to open one.
Manu Sporny: maybe we are not thinking enough about ungenerous readings-- we don't want people marked as "noncompliant" for having been compliant and having passed a test suite before breaking changes
Michael Prorock: +1 manu - wording and appearances are very important right now
Manu Sporny: and we also don't want to hand a "gotcha" opportunity to those who will comb through our github looking for evidence that we aren't running a proper WG here
… or that we've wasted effort
Daniel Burnett: +1 manu
Drummond Reed: I put a link to a sidestepping solution-- a 1.0 compliant table distinct from the existing table that includes all the provisionals as-is
… as long as there is some contextualizing explanation above both
Orie Steele: basically, we need PRs... there are already enough issues....
Drummond Reed: I will work with Ryan on doing this in PRs
… if the group supports it
Ryan Grant: First of all, Manu thanks for correcting the record on the amount of interop that these specs have already achieved
… I wasn't trolling to be annoying, I was hoping to avoid value judgments or partisanship in the editing of this registry
… just to explain the choice of words, even if i support solutions using a diff word
@rxgrant We didn't get any objections in the DID WG meeting today, but we didn't get any strong reactions in general. So here's my proposal: if you're willing to update your PR, let me know if you want me to draft text for the intro paragraphs for each of the two tables. Or alternately just go ahead and update your PR and I can comment on that. Whichever you prefer.
I agree in principle with Drummond's proposal and I think it get's us mostly there. Some further refinements I'd suggest -
- change the SHOULD to a MUST. I don't see any reason that we shouldn't include those details.
- New statuses need to be clearly defined what they mean. 2a. what constitutes "production" readiness? 2b. What constitutes an acceptable test suite? 2c. How do we define "approved" standard for status 4? E.g. a spec that contains a single sentence for a security/privacy considerations section isn't worth "approving". A spec that doesn't have normative statements isn't worth "approving". A spec that has a strong dependency to a particular implementation isn't worth "approving". (my opinion here - curious if WG consensus agrees)
So at a high level I'm at a major +1 to this proposal (and have been for awhile now - thanks for re-proposing it for the 3rd time @talltree) and think with a bit of more specifics about the details in a follow up PR to flesh out the details of point 2a through 2c of this registry we can make this work. Would others here prefer I open a separate issue to discuss the requirements or do we want to consider that here if people agree this is necessary?
Here are the methods that IMHO don't have a reasonable spec at a reasonable URL that, at minimum, addresses how to read a DID Document from the VDR:
some variant of a 404
- did:twit (Twit DID method) has a github link that works but it's the wrong column, while the spec column is a github link that redirects to a 404.
- did:op (Ocean Protocol) manages to 404 at a Github link
- did:dom (Dominode) has no link posted at all
didn't bother posting a DID Method spec that describes how to read a DID Document from the VDR
- did:did (DID Identity DID Method) does not point to any spec, rather marketing material
- did:ion (ION DID Method) points to documentation about libraries that incorporate the method, not a DID Method specification
posted a DID Method specification that takes a form too confusing for the author of this comment to figure out how to retrieve the DID Document
- did:ala offers resolution instructions that include "Create the DID Document"
- did:elem, under its subsection for reads, refers to the sidechain spec, but it's a dead link (404).
- did:gatc
- did:dual
Earlier I made a comment about a DID Method with a very short name. But they're building stuff, so the comment wasn't appropriate.
with a bit of more specifics about the details in a follow up PR to flesh out the details of point 2a through 2c of this registry we can make this work. Would others here prefer I open a separate issue to discuss the requirements or do we want to consider that here if people agree this is necessary?
@kdenhartog I see no reason not to just to continue to refine this proposal here in this issue and then, if @rxgrant is up for it, he can revise his PR #341 to reflect the outcome.
I also agree that we need to define reasonably complete compliance requirements for each of the status tags in the new table. Following are strawman proposals to flesh out your suggestions.
Note that for all of these, we should specify that "Determination of compliance shall be made by the then-current DID Spec Registries editors."
Requirements for the "v1.0 compliant" status tag
- Registrant MUST submit a URL for a publicly available DID method specification hosted in a reasonably stable repository (e.g., standards body, GitHub, dedicated microsite).
- The DID method specification MUST comply with the requirements specified in section 8 of the DID 1.0 specification.
- The proposed DID method name MUST NOT conflict with the name of any previously registered method.
Requirements for the "In production" status tag
- Registrant MUST submit a URL for publicly available documentation, hosted in a reasonably stable repository, of production usage of the DID method.
- Such documentation MUST include instructions for how an implementer may engage to use the DID method in production.
Requirements for the "Test suite available" status tag
- Registrant MUST submit a URL for publicly available documentation, hosted in a reasonably stable repository, of a test suite for the DID method that is publicly available to any implementer.
- Registrant MUST also submit reports signed by two independent implementers documenting the results of their implementations having successfully passed the test suite.
Requirements for the "Approved open standard" status tag
- Registrant MUST submit a URL for the publicly available DID method specification that has been formally approved by a non-profit standards development organization.
I'm sure I missed some but at least it's a start.
I broke the conversation down into individual status tags. I've added a few additional requirements to link the statuses together and then added a few specific questions, but it's probably better to break these down into separate PRs since some are going to be more controversial then others. I've raised some of the edge cases I think may arise in my responses below.
V1.0 Compliant Response
Registrant MUST submit a URL for a publicly available DID method specification hosted in a reasonably stable repository (e.g., standards body, GitHub, dedicated microsite).
The DID method specification MUST comply with the requirements specified in section 8 of the DID 1.0 specification.
The proposed DID method name MUST NOT conflict with the name of any previously registered method.
Agree with this one as it stands ^.
In Production response
Requirements for the "In production" status tag
1. Registrant MUST submit a URL for publicly available documentation, hosted in a reasonably stable repository, of production usage of the DID method. 2. Such documentation MUST include instructions for how an implementer may engage to use the DID method in production.
Agree with these and have added one improvement that I'm sure you implied as well:
### Requirements for the "In production" status tag
1. All requirements from the "V1.0 Compliant" status MUST be met.
2. Registrant MUST submit a URL for publicly available documentation or code, hosted in a reasonably stable repository, of production usage of the DID method.
3. Such documentation MUST include instructions for how an implementer may engage to use the DID method in production.
Test Suite Available response
Requirements for the "Test suite available" status tag
1. Registrant MUST submit a URL for publicly available documentation, hosted in a reasonably stable repository, of a test suite for the DID method that is publicly available to any implementer. 2. Registrant MUST also submit reports signed by two independent implementers documenting the results of their implementations having successfully passed the test suite.
Agree with this one in principle and have added a few improvements:
### Requirements for the "Test suite available" status tag
1. All requirements from the "In Production" status MUST be met.
1. Registrant MUST submit a URL for publicly available documentation, hosted in a reasonably stable repository, of a test suite for the DID method that is publicly available to any implementer.
2. Registrant MUST also submit reports signed by two independent implementers documenting the results of their implementations having successfully passed the test suite.
3. The test suite is expected to be testing all of the normative statements made within the specification document.
This one definitely is going to need a bit more fleshing out still. Here's some follow up questions:
- Is a did method that's built as a patented method acceptable?
- Is it acceptable that both implementations depend on the same library?
- What qualifies as a good test suite here? -> I'm hoping most of these can be cleared up by just relying on W3C requirements for this.
Approved open standard response
Requirements for the "Approved open standard" status tag
1. Registrant MUST submit a URL for the publicly available DID method specification that has been formally approved by a non-profit standards development organization.
Slight modification but looks good:
### Requirements for the "Approved open standard" status tag
1. All requirements for the "Test suite available" status MUST be met.
2. Registrant MUST submit a URL for the publicly available DID method specification that has been formally approved by a non-profit standards development organization.
Some edge cases worth considering here:
- Does a standard that is paid for count? I want to say No, but don't really want to stir a political pot between ISO and W3C.
- Does a standard that doesn't align with W3C's patent policy count? E.g. if the standard was built in a way that requires licensing to use commercially?
@kdenhartog Great stuff. I had no idea you do accordion-style subsections in a comment. (I can't see the source — offline let me know how you did that.)
In any case, I agree that it is looking best to break into multiple PRs. I would suggest this breakdown:
- One PR (maybe the one @rxgrant started #341) to change the layout to three subsections:
- A subsection for the new table, with its own intro paragraph.
- A subsection for the old table, with its own intro paragraph.
- A subsection following the other two for "DID Method Registration Policies"
- Under "DID Method Registration Policies", one PR for each set of requirements for a particular status tag:
- v1.0 Compliant
- In Production
- Test suite available
- Approved open standard
- Deprecated
So that's 6 PRs in total. Whatchathink?
I had no idea you do accordion-style subsections in a comment. (I can't see the source — offline let me know how you did that.)
It's a feature that gets added by an extension I use in my browser called refined-github. You can manually achieve it with the following additional text as well (I've escaped it here with the three-tick code blocks, but it works as expected when not inside that).
<details>
<summary>My title of accordian subsection</summary>
My contents of the according subsection
</details>
I have deep concerns about "in production" and "approved open standard" because I've seen multiple DID Methods use both monikers for alpha software. I won't point fingers, but some of them have participated in our groups over the years.
As someone that has to review PRs for new methods, I don't want to fight people that are claiming that they have a "global standard" or are "in production".
Each of these statements should be backed up by some sort of link to proof.
If you're claiming "registered" you need to point to a spec that meets the minimum requirements for registration.
If you're claiming "fully specified" you need to point to a spec that meets all the DID Method spec requirements in DID Core (really don't like this one, it's a LOT of work for reviewers).
If you're claiming "implemented" you need to point to a source code repository where the implementation exists.
If you're claiming "v1.0 compliant" you need to point to a source code repository where the latest tests exist AND demonstrate no errors from the test suite.
... and so on.
All of this led me to wake up this morning with an idea:
What if we just shifted the DID Method registration process to be more data-driven. That is, we do some extensions to ReSpec that change entries to this format:
<div data-did-method-name="example"
data-did-method-spec="https://did.example/spec.html"
data-did-method-implementation="https://did.example/repo.html"
data-did-method-test-suite="https://did-test-suite.example/reports#example"
/>... whatever extra info the DID Method registrant wants to add here</div>
... and so on. That way, we can auto-generate the labels (and tables) from data they provide to us.... sort, split, one table, two tables -- the algorithm we use to render can change. We could also externalize this to JSON files, which just creates a level of indirection that may or may not be useful (I'm leaning towards NOT doing that and just having everything in the HTML ReSpec source).
Thoughts?
What if we just shifted the DID Method registration process to be more data-driven. That is, we do some extensions to ReSpec that change entries to this format:
<div data-did-method-name="example" data-did-method-spec="https://did.example/spec.html" data-did-method-implementation="https://did.example/repo.html" data-did-method-test-suite="https://did-test-suite.example/reports#example" />... whatever extra info the DID Method registrant wants to add here</div>
This could be great. I think an externalized JSON file might actually be best for this where we can define effectively a database with additional metadata for each DID method that could help feed resolvers etc. We could then have a build process on the respec that takes that JSON, validates it, and generates the respec section from that JSON. This could be similar to what we have done with the build process on the Traceability Vocab. That way we accomplish a few things:
- Set up the registry more as a true digital registry that can be leveraged by resolvers, test suites, and other tech programatically
- Add a test and build step, so that new PRs with a new or modified DID method entry can be validated for completeness and well formed data
- retain a single respec doc from a presentation to users standpoint without having to redirect to an external file
JSON format could look something like:
"methods": [
{
"name": "example_1",
"spec": "https://did.example/spec.html",
"authors": [
{ "name": "John Doe", "email": "[email protected]" }
],
"network": [ { "name": "Some DLT", "uri": "https://somedlt.example.org" } ],
"status": "provisional",
"implementation": "https://did.example/repo.html",
"test": "https://did-test-suite.example/reports#example",
},
...
]
this obviously could be extended as required to cover additional details and facilitate more capability discovery, etc off the registry
I am totally in favor of a data-driven approach to DID method registrations.
So how do we proceed with this as one or more PRs?