Closed msporny closed 1 year ago
Is this an ESG / "values" registry?
Or a registry for "terms" that have an accompanying "specification".
Will "Bitcoin" or "Ethereum" specific terms be allowed?
Will the registry attempt to warn people about "NIST Backdoors"?
Will the registry attempt to avoid western / eastern cultural bias around lawful access?
How will this registry relate to other "registries" such as:
We might want to start gathering exemplar's that we feel speak to the characteristics of a good registry.
Here are a few answers to the questions posed in the issue:
- Will the registry operate under the new Registry policy at W3C?
Yes.
- Who controls updates/changes to the registry as well as status changes?
The VCWG if it is operational. The CCG if the VCWG is not operational.
- How are extensions deprecated?
Extensions are deprecated by the currently active specification Editors/Authors. If an extension is abandoned, with none of the Editors/Authors responding, the VCWG has the authority to deprecate the extension. If an extension is deemed to be dangerous or unmaintained by the VCWG, the VCWG can deprecate the extension.
- Do we want to record a certain level of standardization?
Yes.
- Do we want to allow experimental entries?
Yes.
- When will we pull the registry into the VCWG?
We should do this before November 2022.
Is this an ESG / "values" registry?
No, it is not.
Or a registry for "terms" that have an accompanying "specification".
Yes, a specification must be provided.
Will "Bitcoin" or "Ethereum" specific terms be allowed?
If a registration will be included if it meets the required acceptance criteria.
Will the registry attempt to warn people about "NIST Backdoors"?
The registry will point to specifications that will have a Security Considerations section.
Will the registry attempt to avoid western / eastern cultural bias around lawful access?
The question is too vague to answer. In general, if a registration will be included if it meets the required acceptance criteria.
How will this registry relate to other "registries" such as:
Relationships to other registries will most likely occur through the specifications associated with the extension points.
A registration MUST be a JSON file that conforms to the following JSON Schema:
---
title: Verifiable Credentials Extensions Registry Entry
description: This schema defines the shape of Verifiable Credentials Extensions Registry entry.
type: object
additionalProperties: false
required:
- name
- category
- status
- specification
- maintainerName
- maintainerEmail
properties:
name:
description: The name of the property or class being registered.
type: string
maxLength: 512
category:
description: The category in which to put the extension.
type: string
enum:
- property
- proof
- status
- schema
- refresh
- terms-of-use
- evidence
status:
description: The status of the entry in the registry
type: string
enum:
- experimental
- withdrawn
- tested
- standardized
- deprecated
specification:
description: An active URL that resolves to a human readable specification
type: string
maxLength: 512
maintainerName:
description: A person or organization which responds to maintenance requests
type: string
maxLength: 512
maintainerEmail:
description: An email associated with the entity that responds to maintenance requests
type: string
maxLength: 512
maintainerWebsite:
description: A website that describes the maintainer in more detail
type: string
maxLength: 512
implementationReport:
description: An active URL that resolves to a human readable website describing
implementation interoperability
type: string
maxLength: 512
example: {
# These fields are required
"name": "example",
"category": "property",
"status": "experimental",
"specification": "https://vc.example/example-specification/",
"maintainerName": "W3C Credentials Community Group",
"maintainerEmail": "public-credentials@w3.org",
# These fields are optional
"maintainerWebsite": "https://w3c-ccg.github.io/",
"implementationReport": "https://implementations.example/report/"
}
Here are a list of proposals that the VCWG could run to determine the characteristics of the VC Extensions Registry. These proposals are modeled after the ones that achieved consensus in the DID Working Group:
PROPOSAL: The VC Extensions Registry will be operated as a W3C Registry by the VCWG as defined in the W3C Process here: https://www.w3.org/2021/Process-20211102/#registries
PROPOSAL: As a starting point, the VC Extensions Registry entries MUST conform to the registry registration JSON schema defined here: https://github.com/w3c/vc-data-model/issues/909#issuecomment-1236391481
PROPOSAL: As a starting point for the VC Extensions Registry, the current Editors of the VC Data Model specification will be responsible for maintenance of the VC Extensions Registry. The VCWG may make consensus-based decisions regarding adding, replacing, or removing registry maintainers.
PROPOSAL: As a starting point for the VC Extensions Registry, any name or value of a property MUST be indicative of its function ensuring to avoid generic terms such as "myProperty" or "foo".
PROPOSAL: As a starting point for the VC Extensions Registry, if there are copyright, trademark, or any intellectual property rights concerns, the addition and use MUST be authorized in writing by the intellectual property rights holder under a F/RAND license. Examples include names that use trademarked brand names, property names that utilize the titles of copyrighted works, and patented technology that would cause the use of the extension to require licensing a patent.
PROPOSAL: As a starting point for the VC Extensions Registry, any addition MUST NOT create unreasonable legal, security, moral, or privacy issues that will result in direct harm to others. Examples of unacceptable additions include any containing racist language, technologies used to persecute minority populations, and unconsented pervasive tracking.
PROPOSAL: As a starting point for the VC Extensions Registry, entries MUST NOT be removed, only deprecated or withdrawn.
PROPOSAL: As a starting point for the VC Extensions Registry, the maintainers of the VC Extensions Registry MUST consider all of the policies associated with the registry when reviewing additions to the registry and MUST reject registry entries if they violate any of the stated policies. Entities registering additions can challenge rejections first with the W3C Verifiable Credentials Working Group and then, if they are not satisfied with the outcome, with the W3C Staff. W3C Staff need not be consulted on changes to the VC Extensions Registries, but do have the final authority on registry contents. This is to ensure that W3C can adequately respond to time sensitive legal, privacy, security, moral, or other pressing concerns without putting an undue operational burden on W3C Staff.
PROPOSAL: As a starting point for the VC Extensions Registry, entries that are identified to cause security, privacy, or interoperability problems MAY be marked as such at the discretion of the maintainers of this registry, and if possible, after consultation with the entry maintainer.
PROPOSAL: As a starting point for the VC Extensions Registry, any submission to the registries that meet all the criteria listed in the registration process will be accepted for inclusion. The registry will enumerate all known mechanisms that meet a minimum bar, without choosing between them.
The proposals looks good. I don't see one that covers this snippet from the preceding bullet list of answers —
If an extension is deemed to be dangerous or unmaintained by the VCWG, the VCWG can deprecate the extension.
— which I'd edit slightly, anyway, for clarity —
If an extension is deemed by the VCWG to be dangerous or unmaintained, the VCWG can deprecate the extension.
— or for fewer words, and possibly even more clarity —
If the VCWG deems an extension to be dangerous or unmaintained, the VCWG can deprecate the extension.
@msporny Why wouldn't we use namespaces/contexts here instead? Isn't the whole point of such things to avoid the need for a registry?
PROPOSAL: In order to register an extension, you must implement and submit a complete test suite for it.
The objective being to keep "experimental" stuff that is literally not even tested out of the registry... there is a lot that can be done with JSON-LD / RDF without registering at a central choke point.
@lrosenthol wrote:
@msporny Why wouldn't we use namespaces/contexts here instead? Isn't the whole point of such things to avoid the need for a registry?
Yes, you're right. Though, there is always a contingent that argues strongly for a registry. :)
My personal opinion: I have found that even in the "decentralized extensibility" norm that JSON-LD brings to the table, it's useful to have a place that lists all known extensions as a point of coordination. In some cases, this has led separate teams to get in touch with each other because they were previously unaware of a particular technology being worked on by another team half-way around the world. I'm yet to be convinced that the management overhead is worth this outcome, though... if we could figure out a way to automate this "registry" based on "things we're seeing in the wild", that would be better. For example, if implementers had a way of submitting new JSON-LD Contexts/terms they're seeing in the wild from their production systems, that could get us to automating some aspects of the registry.
@OR13 wrote:
The objective being to keep "experimental" stuff that is literally not even tested out of the registry.
One possibility here is to have experimental stuff "hidden by default". That's one of the reasons I'm proposing that status is listed. By default, the registry would only show things that have been "standardized", and people that haven't implemented an interoperability test suite won't show up (by default). That approach attempts to balance having too many experimental items in the registry (which is the mistake made in the DID Spec Registries) and not knowing what's in development (which can result in unecessary, duplicate work).
When will we pull the registry into the VCWG?
We should do this before November 2022.
why is it November, Manu?
why is it November, Manu?
It's an arbitrary deadline I picked out of thin air to suggest "sooner would be better than later". :)
One possibility here is to have experimental stuff "hidden by default".
I don't really want that... I prefer experimental stuff rely on perma-id, or ccg, or elsewhere.
That approach attempts to balance having too many experimental items in the registry (which is the mistake made in the DID Spec Registries) and not knowing what's in development (which can result in unnecessary, duplicate work).
I'm not sure it was a mistake.... for did methods... it was a mistake to conflate the registry for methods, with the registry for terms that can be used with interoperability.
The issue was discussed in a meeting on 2022-09-07
For example, if implementers had a way of submitting new JSON-LD Contexts/terms they're seeing in the wild from their production systems, that could get us to automating some aspects of the registry.
VC Extensions are rather more complex, but we might consider starting with something like the prefix.cc model.
By which I mean, there's no blessing or vetting implied by being listed in the VC Extension Registry; anyone can submit (via some relatively simple form) the stuff they're encountering in the wild and/or building into their own production systems. Overlapping/conflicting submissions get some degree of popularity contest, but this doesn't prevent people from acting according to their view/vote when it differs from the popular vote result.
This implementation might require some sponsor to maintain the relevant infrastructure (assuming it's beyond W3C, as such), which might (I am not qualified to assess this) be implementable by modifying the code for prefix.cc.
+1 to aligning with the W3C registry process. I'd like more info on how we can reasonably keep this up to date and maintain a standard of excellence to enable robust interop.
I asked Ivan and Wendy about the W3C registries process. The W3C does have a way of designating a spec as being a registry. What it does not have is an independent entity to administer registries (like IETF has IANA) or an objective process for doing so (designated experts appointed by the IESG to make yes/no decisions based on objective instructions to the designated experts written into the specifications).
As a result, working groups and community groups administer W3C registries. This can go horribly wrong, as anyone who witnessed the DID working group attempting to administer its registries can attest. When working groups are involved, there's a temptation to apply value judgements to the registration process, destroying the critical objectivity of the process.
The unfinished state of the W3C registry process also leaves open the question of what happens to the registry when the working group and/or community group tasked with administering the registry dissolves. To my knowledge, the W3C has not answered this question.
Therefore, I believe that this working group should make a definitive decision not to run its own registries, nor to have a W3C community group do so, which is subject to the same dysfunctions. There's a better way that's proven that we can adopt.
Knowing that the W3C did not have a functioning long-running registry process, the W3C WebAuthn working group chose to have IANA administer its registries. It did so by creating an RFC - https://www.ietf.org/rfc/rfc8809.html - to establish the registries it needed with IANA. To this day, the designated experts oversee registrations originating in W3C (and other) specifications in an orderly and objective manner. IANA will survive the termination of the VC working group and continue functioning. This is the mature industry registry model that we should adopt.
As I did for WebAuthn, I'd be willing to author the RFC(s) establishing the registries that we need.
-- Mike
P.S. There's a whole RFC about registries. https://www.rfc-editor.org/rfc/rfc8126 . It's well worth a read.
I like the option of having an RFC establish our registries.
One of the challenges I see with registries is the "industry specific extensions" problem.
For example, we are currently maintaining:
I don't think we want IANA to be the only responsible party for decentralized semantics.
I do think we want IANA to be responsible for core specification terms.
I can imagine an IANA registry for "Industry Specific Verifiable Credential Vocabularies", here would be an example:
Documentation | Context | Controller |
---|---|---|
https://w3id.org/traceability | https://w3id.org/traceability/v1 | ietf-rats-wg, ietf-scitt-wg |
https://w3c.github.io/wot-discovery | https://w3c.github.io/wot-discovery/context/discovery-context.jsonld | w3c-wot |
Documentation | Context | Controller |
---|---|---|
https://w3id.org/vc/status-list | https://w3id.org/vc/status-list/2021/v1 | w3c-vc-wg-cg |
In this model:
(do we have a list - registry to register what..? data integrity crypto suites..?)
In this model:
- IANA maintains all registries
- A registry can contain vocabularies
- A vocabulary can be controlled by a WG at IETF / W3C
- A vocabulary can be controlled by a Community Group, such as W3C CCG or DIF.
this seems extremely sane to me
The issue was discussed in a meeting on 2022-11-02
The issue was discussed in a meeting on 2023-01-18
- IANA maintains all registries
It makes sense for us to use IANA registries where they exist, but I'm not sure we have the power, authority, or right to tell IANA they have to manage one or more new registries for us (whether "us" is W3C writ large, W3C VCWG, or W3C CCG)....
- IANA maintains all registries
It makes sense for us to use IANA registries where they exist, but I'm not sure we have the power, authority, or right to tell IANA they have to manage one or more new registries for us (whether "us" is W3C writ large, W3C VCWG, or W3C CCG)....
I do not think we have the right (as W3C). We can negotiate, but that is all.
The issue was discussed in a meeting on 2022-09-15
Per my action item from the W3C VCWG F2F in Miami, I have created a "Verifiable Credential Specifications Directory" for consideration by the VCWG:
https://github.com/msporny/vc-specs-directory
A summary of what this repository does:
myspec.json
file to the specifications/
directory.This issue will be closed once this directory is adopted as a work item in the VCWG or an alternative is put forward and adopted.
Presumably the plan is also to move the repo from /msporny/
to somewhere beneath /w3c/
upon adoption as described?
Presumably the plan is also to move the repo from
/msporny/
to somewhere beneath/w3c/
upon adoption as described?
Yes, definitely.
I only put it on my personal Github repository based on a request by @OR13 to (paraphrasing): "Start from scratch. Don't include any previous attempt at the problem to eliminate any negative feelings any WG members might have against our previous VC Extensions Registry and DID Specifications Registry approaches".
@msporny would this result in us closing #975? I am also curious what you suggest we propose to the CCG for their registry.
@msporny would this result in us closing #975? I am also curious what you suggest we propose to the CCG for their registry.
Yes, it would close #975 (in favor of bringing in the VC Specifications Directory). We would tell the CCG to update the "VC Extensions Registry" (which I'm an Editor on) to redirect it to the VC Specifications Directory. I don't expect people to complain because it'll end up pointing to the same specs the VC Extensions Registry points to, but with a lower barrier to entry (and far less judgement on whether a particular extension is "good" or not).
How is ordering handled? Alpha by a particular JSON field?
How is ordering handled? Alpha by a particular JSON field?
I was thinking of randomizing the ordering for each section using the year+month as a seed to the random number generator. I am not kidding. :)
That would produce semi-stable list ordering every month (like if you keep coming back to the directory and visually searching by where an entry was in a list the last time you looked at it... "it was around the bottom of the VC Types section") but destroy any spec name gaming attempt across time. We'd also have anchors beside each entry so you could just click on the anchor and share that link with folks so, even though the list is randomized, you'd end up looking at the entry the person that shared the link with the fragment ID shared with you.
We could also have a sorting column indicator, so people could sort by spec name, maintainer name, etc.... though, most would just sort by spec name.
Just some thoughts, open to simpler approaches.
The issue was discussed in a meeting on 2023-03-01
List of resolutions:
vc-spec-dir
, converting all concerns raised during the call to issues in the Github repository..The VC Specs Directory now exists, which defines policies:
https://w3c.github.io/vc-specs-dir/#adding-a-specification-entry
The adoption of that work, and the "definition of policies for a directory of related work" closes this issue.
We need to define policies for the VC Extension Registry to answer questions such as:
This issue is designed to track these policy questions regarding the VC Extension Registry.