w3c / vc-specs-dir Goto Github PK

View Code? Open in Web Editor NEW

11.0 14.0 14.0 111 KB

Verifiable Credential Specifications Directory

Home Page: https://w3c.github.io/vc-specs-dir/

License: Other

JavaScript 3.50% HTML 96.50%

credentials vc verifiable w3c vc-wg

vc-specs-dir's Introduction

Verifiable Credential Specifications Directory

This repository contains a directory created by the W3C Verifiable Credentials Working Group (VC WG) for the purpose of discovering specifications known to exist in the Verifiable Credentials Ecosystem.

An Editor's Draft of this repository is available at https://w3c.github.io/vc-specs-dir/.

Adding New Entries to the Directory

In order to add a new specification to this directory, you must add a JSON file to the ./specifications directory and open a pull request to add the file to this repository.

Here is an example specification entry:

{
  // These fields are required
  "name": "Example VC",
  "summary": "Used to demonstrate examples for Verifiable Credentials.",
  "specification": "https://example.github.io/example-spec/",
  // categories include: vc, credentialStatus, credentialSchema,
  //                     refreshService, termsOfUse, evidence, and proof
  "category": "vc",
  "maintainerEmail": "[email protected]",
  // These fields are optional
  "maintainerName": "Example Community Group",
  "maintainerWebsite": "https://example.github.io/",
  // RDF vocabularies in yml2vocab format
  "vocabulary": ["https://example.github.io/vocabularies/example.yml"]
}

Your Pull Request will be automatically validated, please ensure that all of the automated tests pass (no errors reported) or your submission will not be reviewed. Common reasons for failed validation includes invalidly formatted JSON files and missing mandatory fields. There will be a checklist that you are expected to complete and attest to its accuracy. Once you submit your request, your pull request will be reviewed by the directory maintainers. Changes regarding the required criteria may be requested. If there are no objections or changes requested, your specification will be added after a minimum of 7 days and a maximum of 30 days.

Adding Anything Else to this Directory

Use the standard fork, branch, and pull request workflow to propose changes to the directory. Please make branch names informative—by including the issue or bug number for example.

Editorial changes that improve the readability of the directory or correct spelling or grammatical mistakes are welcome.

Non-editorial changes MUST go through a review and approval process that is detailed in the directory.

Please read CONTRIBUTING.md, about licensing contributions.

Code of Conduct

W3C functions under a code of conduct.

VC Working Group Repositories

vc-specs-dir's People

Contributors

Stargazers

Watchers

Forkers

bshambaugh robcoyle913 decentralgabe or13 david-chadwick jandrieu mizukisonoko alexcolganld lleifermann m00sey xaviaracil jyasskin brentzundel anthonycamilleri

vc-specs-dir's Issues

Organize at least W3C Recommendations in their own section

Sections for other organizations may also be appropriate.

Rename repository to `vc-specs` before FPWD

We should rename the shortname to vc-specs.

We will still make it clear that the document is a directory and not an official registry, that's an important distinction to make in the document. An alternative is to expand the name to vc-spec-directory to align w/ did-spec-registries. What we have right now is a strange middle-ground in naming.

/cc @iherman @jandrieu @OR13 @mprorock @dlongley @TallTed

Add an example JSON file the "how to register" section

Seems to me that parsing YAML is a fairly high barrier. An example would help.

Remove JSON web signatures securing mechanism

The description of this security mechanism is that it has now been withdrawn. So shouldn't we also remove it from the directory?

I guess the higher level discussion that the WG needs to have, is what shoud the directory contain. Currently the Introduction states "unofficial directory for all known Verifiable Credential specifications". But does this mean all known usable or active specifications, or all known historical, superceded, and withdrawn specifications?

Multiple Maintainers

Currently a directory entry only allow a single entity to be listed as the maintainer, with a single email address and name. For the OIDF IDA specification there are currently two maintainers of the specification, so it is suggested that the maintainer properties should be lists of strings, rather than single strings.

Define all schema validation fields in respec

Provide a definition and help text for all fields in the entry schema.

Turn this into a W3C Draft Registry

There's some discussion on this in #17, but I'll file this focused issue to avoid distracting further from that one's original topic.

This document is referenced by https://www.w3.org/TR/vc-data-model-2.0/#extensibility as the way for implementers to figure out how to implement the various extension points in the VC data model. To make it effective for that purpose:

It should be a normative reference from that document, which implies that it should be able to get to the same maturity as vc-data-model as that goes eventually to REC. Since this document will need to be updated continuously as new extensions are defined, the Registry track seems like the best fit.
The tables here should include the "type" value that indicates the particular extension, and (as they already do) a link to the specification that defines what to do when that "type" value appears. (It's possible some of the extension points use a field other than "type" to identify the extension; I only checked https://www.w3.org/TR/vc-data-model-2.0/#status and https://www.w3.org/TR/vc-data-model-2.0/#securing-verifiable-credentials.)

@TallTed is worried in #14 (comment) that "this feels like a competitor to IANA registration, with little to no gatekeeping, especially as compared to IANA.", but the WG is free to define whatever level of gatekeeping it wants. The "registry definition" "Define[s] the method and criteria by which changes are proposed, approved, and incorporated.", which could easily refer to one of the categories from https://www.rfc-editor.org/rfc/rfc8126.html#section-4, and the W3C "custodian" can be used for the same purpose as IANA's "designated expert". As long as y'all don't create a registry that actually duplicates an existing IANA registry, this seems fine.

I suggest using Specification Required as the criteria by which changes are approved. This ensures that the registry is sufficient for helping implementers figure out how to interoperate, but it doesn't allow any particular standards body to gatekeep which extensions are allowed, as long as they're documented sufficiently.

This document serves as an unofficial directory for all known Verifiable Credential specifications whether they are released by a global standards setting organization, a community group, an open source project, or an individual.

This is an unfortunate expansion of the remit of this directory.

Suggested fix

This document serves as an unofficial directory for specifications related to Verifiable Credentials whether they are released by a global standards setting organization, a community group, an open source project, or an individual.

Importantly, just because something is listed here does NOT make it a Verifiable Credential.

What makes something a verifiable credential is whether or not it meets the normative requirements defined in the VCDM.

w3c / vc-specs-dir Goto Github PK

vc-specs-dir's Introduction

Verifiable Credential Specifications Directory

Adding New Entries to the Directory

Adding Anything Else to this Directory

Code of Conduct

VC Working Group Repositories

vc-specs-dir's People

Contributors

Stargazers

Watchers

Forkers

vc-specs-dir's Issues

Recommend Projects

Recommend Topics

Recommend Org