Define policies for directory of related work

[msporny]

We need to define policies for the VC Extension Registry to answer questions such as:

1. Will the registry operate under the new Registry policy at W3C?
2. Who controls updates/changes to the registry as well as status changes?
3. How are extensions deprecated?
4. Do we want to record a certain level of standardization?
5. Do we want to allow experimental entries?
6. When will we pull the registry into the VCWG?

This issue is designed to track these policy questions regarding the VC Extension Registry.

[OR13]

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:

• https://w3c.github.io/did-spec-registries/
• https://www.iana.org/assignments/jose/jose.xhtml
• https://www.iana.org/assignments/cose/cose.xhtml
• https://toolkit.ncats.nih.gov/glossary/registry-sustainability/

We might want to start gathering exemplar's that we feel speak to the characteristics of a good registry.

[msporny]

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.

[msporny]

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/"
}

[msporny]

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: #909 (comment)

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.

[TallTed]

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.

[lrosenthol]

@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?

[OR13]

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.

[msporny]

@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).

[Sakurann]

When will we pull the registry into the VCWG?

We should do this before November 2022.

why is it November, Manu?

[msporny]

why is it November, Manu?

It's an arbitrary deadline I picked out of thin air to suggest "sooner would be better than later". :)

[OR13]

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.

[iherman]

The issue was discussed in a meeting on 2022-09-07

• no resolutions were taken

View the transcript

2.1. Define policies for VC Extension Registry (issue vc-data-model#909)

See github issue vc-data-model#909.

Kristina Yasuda: Manu, can you update us on this?

Manu Sporny: We theoretically have a registry for VC Extensions registries.
… I took an action to propose answers to these questions.
… I modelled it on the DID registries.
… These are the initial rules. We will have two years to refine them.
… This is a starting point.

Manu Sporny: proposals are here: #909 (comment).

Manu Sporny: People should read these proposals before TPAC.
… The other thing to note about the proposals is that we're trying to make the registries have a specific format.
… Registrants will fill out a form.
… Then we can create tooling.

Michael Jones: I have a question for Ivan and really for the W3C staff, I know that there have been action items for the W3C in the last few years to create registries and policies so WGs don't have to manage their own registry entries, where are we on that, Ivan?

Ivan Herman: I think the only thing that does exist now, is a formal way of declaring something as a registry.
… I think the only thing that exists now is a formal way of declaring something as being a registry.
… The only thing that that entails today is that the policy of maintaining the registry has to be approved by the AC.

Manu Sporny: The first proposal provides this text: 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.

Michael Jones: First, confirming, there is no plan to develop the equivalent of IANA so there's a neutral party for registries in W3C, right?

Ivan Herman: What you say is correct.

Justin Richer: +1 on using IANA and established processes.

Michael Jones: I'll put this in the issue. The alternative is to use IANA, which is a neutral 3rd party which won't do what the DID WG did and make value judgments about whether things are good or bad entries. An example of that is the WebAuthn WG established a tool to create registries for IANA.
… I want us to at least consider that since W3C has no registry mechanism of its own. My personal experience watching the DID WG try to maintain its own registries ... I was horrified and we shouldn't do that

Ivan Herman: I'm not aware of any attempt at the W3C to establish the equivalent of IANA, though I am not familiar with the details of what IANA means in this respect.

Michael Jones: I wanted to put some of that out for those on the call now and agree we should discuss at TPAC, I'm on the hook for doing a registries presentation already.

Shigeya Suzuki: +1 to mike.

Kristina Yasuda: The purpose of raising this was for people to be aware of the registry issue.

Phil Archer: When I add things to an IANA registry it basically just has to be in a stable document.
… It goes to a designated expert, often Mark Nottingham.
… It's the process that ensures neutrality.

Manu Sporny: +1 to "the neutrality comes from the process".

[TallTed]

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.

[decentralgabe]

+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.

[selfissued]

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.

[OR13]

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:

• https://w3id.org/wallet
• https://w3id.org/traceability
• https://w3id.org/citizenship

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:

Industry Specific Verifiable Credential Extensions Registry

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

Core Data Model Verifiable Credential Extensions Registry

Documentation	Context	Controller
https://w3id.org/vc/status-list	https://w3id.org/vc/status-list/2021/v1	w3c-vc-wg-cg

In this model:

1. IANA maintains all registries
2. A registry can contain vocabularies
3. A vocabulary can be controlled by a WG at IETF / W3C
4. A vocabulary can be controlled by a Community Group, such as W3C CCG or DIF.

[Sakurann]

(do we have a list - registry to register what..? data integrity crypto suites..?)

[mprorock]

In this model:

1. IANA maintains all registries
2. A registry can contain vocabularies
3. A vocabulary can be controlled by a WG at IETF / W3C
4. A vocabulary can be controlled by a Community Group, such as W3C CCG or DIF.

this seems extremely sane to me

[iherman]

The issue was discussed in a meeting on 2022-11-02

• no resolutions were taken

View the transcript

2.2. Define policies for VC Extension Registry (issue vc-data-model#909)

See github issue vc-data-model#909.

Manu Sporny: a bunch of proposals ... we can try to run proposals one by one and see how far we can get.
… there are some concrete proposals and we can see how people react to that.

Brent Zundel: fine with that.
… I'm fine w/ running proposals....

Kristina Yasuda: Discussion at TPAC we need proposals for registries we want, let's come back on what registries we want -- passing how we manage registries wouldn't be actionalble..

Brent Zundel: This is part of vc-extension registry discussion..

Manu Sporny: this is specific to VC extension registry. we have an extension registry today..

Michael Prorock: +1 manu.

Manu Sporny: working group created one and handed it to the CCG.

Michael Prorock: and the CCG is not the right home for that.

Manu Sporny: it is a concrete thing that is out of date but exists today.

Joe: I don't think we have a registry --.

Manu Sporny: It exists, the VC 1.0 created it..

Orie Steele: We should take a inventory of things that need to be in a registry and the things that CCG might want to manage. When W3C looks at CCG and WG, they might not recognize that these are two separate processes... they might thing CCG isn't decision maker. Looking at things like status list and things of that nature. Have the conversation around how to communicate items delegated to CCG for control and what that means..
… What is means today and what it means tomorrow. That will be helpful to elaborate upon..

Phillip Long: This sounds like a good topic for the CCG, that is, who controls a registry and what are the processes by which the operate..

Michael Jones: I believe in past discussions in this WG, including at TPAC, there was consensus to extend that we have registries that we should control them. I agree with Joe that a registry that shares name at CCG has no standing and we should decide which registries we're going to have and operate them or delegate to IANA to operate them..

Drummond Reed: +1 to having a registry controlled by this WG..

Phillip Long: +1 to an inventory to the registry.

Michael Prorock: CCG Chair Hat on, I believe based on everything I've seen to date, that Manu is correct. VCWG 1.0 created this and transferred management to CCG. I don't think Community Group or Business Group is a place to have normative ramifications. Orie is on to something good, CCG Chairs can have a full dedicated meeting about this -- point by point items that are at CCG that should be controlled as part of VCWG, pointing to IANA and other items -- any motions required at CCG so items can transition appropriately to normative body..

Orie Steele: +1 MikeP we should create clarity and remove uncertainty on this, but we can't ignore previous resolutions from W3C WGs regarding W3C CCG..

Manu Sporny: +1 mikep.

Brent Zundel: We have had good conversation, what is concrete next step to move forward?.

Manu Sporny: I'm hearing two things -- JoeA's objection, and inventory of things that go into the registry....

Michael Prorock: We just need a list of repos to get everything handled..
… From CCG standpoint, I recommend that we also classify items in inventory, we might have non-registry items planned for FCGS so would be helpful if we have that list, some of that work is in VCWG charter, but there are items like this that are not. We shouldn't limit ourselves when taking that inventory of things to move over from CCG.

[iherman]

The issue was discussed in a meeting on 2023-01-18

• no resolutions were taken

View the transcript

4.2. Define policies for VC Extension Registry (issue vc-data-model#909)

See github issue vc-data-model#909.

Kristina Yasuda: we're discussing the extension registries.
… suggest removing discuss, not sure how to process this.

Manu Sporny: we could run orie's proposal... for what would go into it.

Kristina Yasuda: ok, i see the proposal.
… we can discuss now.

Orie Steele: I am looking at the proposal, we have a DID Spec Registry that looks something like this..
… We could have a NOTE that has this in there, we could refer elsewhere, I don't know how to proceed. I know how to maintain a registry, I don't know how this WG wants to handle a registry and potential extensions..
… I do think we should decide on this soon since we're seeing extensions pop up..

Kristina Yasuda: well, I might be remembering wrong, but there seemed to agreement on using IANA to manage registries, instead of W3C.

Manu Sporny: there was a suggestion to that effect, but there were objections.
… at the face to face, i proposed a lightweight approach like what we did for did spec registries... which i hesitate to suggest, but it has worked well for terms / extensions.
… we could propose an empty registry.
… and establish a process for updating it.
… and then let it grow from there.
… I like the structure orie proposed, more than what we did in did core.
… proposal would be to create a blank document with a process, and use a note to maintain it.

Joe Andrieu: we only need to define terms in a spec... because we have @context, any community can extend without a registry.
… if we create our own registry, we will elevate certain terms above others... and it can create problems where people think they need to register things to use them... it undermines our entire model....
… it prevents decentralization, and disables the promise of this work.

Steve McCown: +1 for JoeAndrieu's comments about registries.

Dave Longley: +1 to joe -- doesn't seem like we necessarily need a registry (nor want to maintain them) and it can be harmful in the ways he says.

Joe Andrieu: we also have a horrible track record, wrt registries... if we do this again, its going to make things worse..

Gabe Cohen: I don't think we're undermining decentralization.
… we would be undermining the JSON-LD data model though.

Joe Andrieu: +1 for other options.

Gabe Cohen: adding more options for extension helps.

Joe Andrieu: -1 for this work centralizing a de facto registry.

Manu Sporny: joe would you be ok with a list of "known" specs?.
… just a list of items, not a "namespace" for terms... just a "list of specs" with their change controllers.

Joe Andrieu: agree up until the point of "change controllers"..
… as soon as we add change controllers, it violates the consensus model, and creates problems.

Kristina Yasuda: manu proposes a blank document and a process, that seems like a path forward..

Gabe Cohen: @manu mispoke. yes, we are json-ld data model, even if json-ld is not the only mechanism for extension.

Kevin Dean: good to publish, but not as a normative specification.

Joe Andrieu: I agree with gabe, we deserve additional mechanism for extensibility, i just don't think the W3C should manage it..

Phillip Long: Phil-ASU has joined #vcwg.

Joe Andrieu: I've not seen an proposals other than have the W3C run it.

Manu Sporny: not hearing an objection to creating a blank document, that has a process that does not favor anything, and just points to other stuff....
… should I do that?.

Joe Andrieu: don't call it a registry, call it a directory of related work.

Kristina Yasuda: where would this be?.

Gabe Cohen: https://w3c-ccg.github.io/vc-extension-registry/.

Manu Sporny: we have a thing... we either create a new repo.

Orie Steele: I suggest creating a new repo so we don't pull in political baggage..
… +1 to create new blank repo and basic process, named as Joe has requested, send it to list for review. I would not take anything as input to the work..

Manu Sporny: +1 Orie.

Gabe Cohen: we do have an extension registry... I have an issue to move it over, sounds like we don't want to do that..

Manu Sporny: This thing sounds like it's controversial now: https://w3c-ccg.github.io/vc-extension-registry/.

Gabe Cohen: we should do something to the existing registry.

Manu Sporny: +1 to deprecate/rename CCG registry..

Kristina Yasuda: any objections to editors creating a blank document and process for the group to review.
… ok, lets start with that.
… adding ready for PR... gabe, can you open an issue... are there objections to deprecating the ccg registry.

Dave Longley: no objection, just seems like it might be unnecessary work... seems like it might cause headaches in the future -- maybe depends on what the process says in the PR..

Kristina Yasuda: can you document we need to do something to the existing registry.

Manu Sporny: we don't have authority over ccg, lets do things one at a time.

Gabe Cohen: issue opened: w3c-ccg/vc-extension-registry#14.

[TallTed]

1. 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)....

[iherman]

1. 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.

[iherman]

The issue was discussed in a meeting on 2022-09-15

• no resolutions were taken

View the transcript

5.8. Define policies for directory of a related work (issue vc-data-model#909)

See github issue vc-data-model#909.

Manu Sporny: We had consensus to define a directory of related work.

[msporny]

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:

• It is NOT a registry -- it has no official standing; specifications listed in it are not vetted.
• It is a directory that links to known specifications in the Verifiable Credentials Ecosystem.
• There are only three requirements for getting into the directory: 1) pass the JSON Schema for your specification entry, 2) don't violate anyone else's intellectual property, and 3) don't create unreasonable legal, security, or moral issues that result in direct harm to others.
• Adding a specification entry is as simple as committing a myspec.json file to the specifications/ directory.
• All entries are syntax-checked using JSON Schema.
• The directory is built from all of the specification entries and grouped by extension point in the Verifiable Credentials Data Model specification.
• There are instructions on how you add a specification entry (which are displayed on each new PR), and an example of such an addition in this PR.

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.

[TallTed]

Presumably the plan is also to move the repo from /msporny/ to somewhere beneath /w3c/ upon adoption as described?

[msporny]

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".

[decentralgabe]

@msporny would this result in us closing #975? I am also curious what you suggest we propose to the CCG for their registry.

[msporny]

@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).

[jandrieu]

How is ordering handled? Alpha by a particular JSON field?

[msporny]

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.

[iherman]

The issue was discussed in a meeting on 2023-03-01

List of resolutions:

• Resolution No. 1: Adopt https://msporny.github.io/vc-specs-directory/ as the "VC Specs Directory" work item in the VCWG tentatively using the shortname vc-spec-dir, converting all concerns raised during the call to issues in the Github repository..
• Resolution No. 2: The W3C VCWG requests that the Credentials Community Group redirect the entire existing Cryptosuites Registry and the Verifiable Credential Extension Registries to the newly adopted VC Specs Directory..

View the transcript

2. VC Specifications Directory.

Kristina Yasuda: are we readiy to talk about specification directories.

Manu Sporny: Verifiable Credential Specifications Directory: https://lists.w3.org/Archives/Public/public-vc-wg/2023Feb/0015.html.

Manu Sporny: yes, we have been talking about registries, some concerns over registries being too centralized.
… there is a proposal out there link above around VC specifications directory.
… many months of arguements around what goes into, or how it goes into a directory.
… this proposal is more light weight.
… to get into the directory you PR to add to the regsitry.
… provide (the right set) of fields, syntax checking fundamentally you can get into the directory by providing extensions or if you extend any of the properties, or if you.
… implement new credentials.
… if you have a spec and it works with VCs this is a good place to be.
… if this becomes a work item, there would be a process for entering the directory, to remove extreme bad usage of the directory.
… open to including as many as we can, omitting anything that would cause direct harm.

See github issue vc-data-model#909.

Manu Sporny: concrete proposal, adopt this as a work item so we can aggrerate specifications.

Joe Andrieu: Question, around control mechanisms, are there any? once an entry is in, who owns it, who updates it.

Manu Sporny: the author would.

Joe Andrieu: prefer to formalize authorization in the specification.
… second question to provide mechanism to avoid gaming of the directory (get their spec to the top).
… concrete ask, how do we provide control and ordering.

Brent Zundel: does this addition of ordering and control need to happen before the work item is adopted?.

Kristina Yasuda: clarification around how you get into the directory.

Orie Steele: thanks for preparing the docuemnt, background on other spec registries.
… no concrete proposal but plus one to manu's comment on registries, we talked about relationship around registries with other groups ccg etc.
… question would ccg be a home for this document vs this working group.
… are we sure this is a work item for this group, could it be maintained by another group, is there a strategic advantage for this group to do it.

Manu Sporny: first point, what happens to the cryptro suite in the ccg, should shut down, it was not maintained like it should have been.
… there are benefits to doing wgvc vs ccg so we're making progess doing it here.
… second item shut down the cyrpto suite in ccg.
… third item is missing in manu's mind :(.

Orie Steele: Thanks Manu, thats what I was hoping to hear..

Samuel Smith: experiencing disputes with with did:keri+1. if we are having a registry that is name squattable the request is to have concrete procedures, look toward IANA.

Kristina Yasuda: can you please indicate if you want to accept this work item.

Brent Zundel: hear concerns around how we go about doing this, this should perhaps be a work item first as a proposal and bring it in.
… then raise issues.

Joe Andrieu: +1 adopting it....
… short version, if we hand over to ccg....

Joe Andrieu: the right to change the rules.

Joe Andrieu: I'll say it here..

Joe Andrieu: +1 to adopting this work item, and fixing the control and ordering questions through consensus.

Manu Sporny: can we convert the conversation to issues on the proposal.

Joe Andrieu: +1 to keeping it in VCWG because handing it to CCG also hands control over the directory rules, which would allow, IMO, too much flexibility to a different consensus process..

Brent Zundel: add "using the shortname vc-spec-dir".

Kevin Griffin: .. draft proposal adopt this as a work item (this being VC speccs directory).

Sten Reijers: question on this, how to deal with collisions.
… just add it to the list?.

Manu Sporny: suggestion is you just add it to the list, post finger wagging.

Joe Andrieu: A book store can readily sell different books with the same name..

Kristina Yasuda: any changes want to see to the proposal in irc.

Manu Sporny: brent suggestion of short name can be worked on before FPWD.
… we don't have to make a short name decision now.

Ted Thibodeau Jr.: "tentatively using the shortname vc-spec-dir".

Manu Sporny: we'll do it before FPWD.

Brent Zundel: short name, we'll work it out.

Samuel Smith: https://www.rfc-editor.org/rfc/rfc8126.html.

Proposed resolution: Adopt https://msporny.github.io/vc-specs-directory/ as the "VC Specs Directory" work item in the VCWG tentatively using the shortname vc-spec-dir, converting all concerns raised during the call to issues in the Github repository.. (Kristina Yasuda)

Manu Sporny: +1.

Brent Zundel: +1.

Sten Reijers: +1.

Joe Andrieu: +1.

Todd Snyder: +1.

Phil Feairheller: +1 to the creating VC Specs Directory proposal.

Andres Uribe: +1.

Dave Longley: +1.

Shigeya Suzuki: +1.

Tobias Looker: +1.

Ted Thibodeau Jr.: +1.

Kerri Lemoie: +1.

Kevin Griffin: +1.

Samuel Smith: See RFC 8126 section 9.5. Contact Person vs Assignee or Owner.

Gabe Cohen: +1.

Steve McCown: +1.

Samuel Smith: +1.

Orie Steele: +1.

Dmitri Zagidulin: +1.

Kristina Yasuda: last call.
… the proposoal is resolved, there are no objections.

Resolution #1: Adopt https://msporny.github.io/vc-specs-directory/ as the "VC Specs Directory" work item in the VCWG tentatively using the shortname vc-spec-dir, converting all concerns raised during the call to issues in the Github repository..

Kristina Yasuda: do we need to run a propsoal around retiring the crypto suite at ccg.

Manu Sporny: will draft, he needs a minute.

Sten Reijers: Looking at https://w3c-ccg.github.io/ld-cryptosuite-registry/, right?.

Kristina Yasuda: and we make the propsoal more specific with regard to reregsitering.

Orie Steele: Also https://github.com/w3c-ccg/vc-extension-registry.

Kristina Yasuda: anything that is duplicative can it only reside in the new directory.

Manu Sporny: no duplication, we will be redirecting.

Kristina Yasuda: can we migrate?.

Orie Steele: typically we do a "client side redirect" or a server side one if w3id.org is used..

Manu Sporny: we'll redirect the whole registry, if they had an old one, they can register.

Manu Sporny: yes, Orie is correct... we're talking about BOTH of those registries..

Orie Steele: noting that there are two registries vc extenstion and crypto suite, are we retiring both.

Kristina Yasuda: draft proposal: The W3C VCWG requests that the Credentials Community Group redirect the entire existing Cryptosuites Registry and the Verifiable Credential Extension Registries to the newly adopted VC Specs Directory..

Proposed resolution: The W3C VCWG requests that the Credentials Community Group redirect the entire existing Cryptosuites Registry and the Verifiable Credential Extension Registries to the newly adopted VC Specs Directory.. (Kristina Yasuda)

Orie Steele: +1.

Sten Reijers: +1.

Manu Sporny: +1.

Dave Longley: +1.

Phil Feairheller: +1.

Joe Andrieu: +1.

Andres Uribe: +1.

Todd Snyder: +1.

Shigeya Suzuki: +1.

Kevin Griffin: +1.

Tobias Looker: +1.

Gabe Cohen: +1.

Kerri Lemoie: +1.

Steve McCown: +1.

Brent Zundel: +1.

Dmitri Zagidulin: +1.

Ted Thibodeau Jr.: +1.

Paul Dietrich: +1.

Resolution #2: The W3C VCWG requests that the Credentials Community Group redirect the entire existing Cryptosuites Registry and the Verifiable Credential Extension Registries to the newly adopted VC Specs Directory..

Manu Sporny: \o/ \o/.

Kristina Yasuda: no minus ones - proposal is resolved.
… thank manu for the document.
… please raise issues if you're worried about collisions etc.
… and an editor give an update on which PRs more attention or special topic call.

[msporny]

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.