w3c-vcdm-ecosystem-graphs - SKILL.md Agent Skill

name: "w3c-vcdm-ecosystem-graphs" description: "Use when implementing ecosystem compatibility and VC graph features in W3C VCDM. Covers ecosystem compatibility, VC graphs, and securing specifications." sections: - "5.11 Ecosystem Compatibility" - "5.12 Verifiable Credential Graphs" - "5.13 Securing Mechanism Specifications"

5.11 Ecosystem Compatibility

There are a number of digital credential formats that do not natively use the data model provided in this document, but are aligned with a number of concepts in this specification. At the time of publication, examples of these digital credential formats include JSON Web Tokens (JWTs), CBOR Web Tokens (CWTs), JSON Advanced Electronic Signature (JAdES), ISO-18013-5:2021 (mDLs), AnonCreds, Gordian Envelopes, and Authentic Chained Data Containers (ACDCs).

If conceptually aligned digital credential formats can be transformed into a conforming document according to the rules provided in this section, they are considered "compatible with the W3C Verifiable Credentials ecosystem". Specification authors are advised to adhere to the following rules when documenting transformations that enable compatibility with the Verifiable Credentials ecosystem. The transformation specification —

MUST identify whether the transformation to this data model is one-way-only or round-trippable.

MUST preserve the @context values when performing round-trippable transformation.

MUST result in a conforming document when transforming to the data model described by this specification.

MUST specify a registered media type for the input document.

SHOULD provide a test suite that demonstrates that the specified transformation algorithm to the data model in this specification results in a conforming document.

SHOULD ensure that all semantics used in the transformed conforming document follow best practices for Linked Data. See Section 4.1 Getting Started, Section 5.2 Extensibility, and Linked Data Best Practices [LD-BP] for additional guidance.

    Note: What constitutes a verifiable credential?

Readers are advised that a digital credential is only considered compatible with the W3C Verifiable Credentials ecosystem if it is a conforming document and it uses at least one securing mechanism, as described by their respective requirements in this specification. While some communities might call some digital credential formats that are not conforming documents "verifiable credentials", doing so does NOT make that digital credential compliant to this specification.

5.12 Verifiable Credential Graphs

When expressing verifiable credentials (for example in a presentation), it is important to ensure that data in one verifiable credential is not mistaken to be the same data in another verifiable credential. For example, if one has two verifiable credentials, each containing an object of the following form: {"type": "Person", "name": "Jane Doe"}, it is not possible to tell if one object is describing the same person as the other object. In other words, merging data between two verifiable credentials without confirming that they are discussing the same entities and/or properties, can lead to a corrupted data set.

To ensure that data from different verifiable credentials are not accidentally co-mingled, the concept of a verifiable credential graph is used to encapsulate each verifiable credential. For simple verifiable credentials, that is, when the JSON-LD document contains a single credential with, possibly, associated proofs, this graph is the default graph. For presentations, each value associated with the verifiableCredential property of the presentation is a separate named graph of type VerifiableCredentialGraph which contains a single verifiable credential or an enveloped verifiable credential.

Using these graphs has a concrete effect when performing JSON-LD processing, which properly separates graph node identifiers in one graph from those in another graph. Implementers that limit their inputs to application-specific JSON-LD documents will also need to keep this in mind if they merge data from one verifiable credential with data from another, such as when the credentialSubject.id is the same in both verifiable credentials, but the object might contain objects of the "Jane Doe" form described in the previous paragraph. It is important to not merge objects that seem to have similar properties but do not contain an id property that uses a global identifier, such as a URL.

5.13 Securing Mechanism Specifications

As described in Section 4.12 Securing Mechanisms, there are multiple strategies that an implementer can use when securing a conforming document. In order to maximize utility and interoperability, specification authors that desire to author new ways of securing conforming documents are provided with the guidance in this section.

Securing mechanism specifications MUST document normative algorithms that provide content integrity protection for conforming documents. The algorithms MAY be general in nature and MAY be used to secure data other than conforming documents.

Securing mechanism specifications MUST provide a verification algorithm that returns the information in the conforming document that has been secured, in isolation, without including any securing mechanism information, such as proof or JOSE/COSE header parameters and signatures. Verification algorithms MAY return additional information that might be helpful (for example, during validation or for debugging purposes), such as details of the securing mechanism. A verification algorithm MUST provide an interface that receives a media type (string inputMediaType) and input data (byte sequence or map inputData). Securing mechanism specifications MAY provide algorithms and interfaces in addition to the ones specified in this document. The verification algorithm returns a verification result with at least the following items:

      [boolean](https://infra.spec.whatwg.org/#boolean) verified

A verification status whose value is true if the verification succeeded and false if it did not.

      [map](https://infra.spec.whatwg.org/#ordered-map) verifiedDocument

A document that only contains information that was successfully secured.

      [string](https://infra.spec.whatwg.org/#string) mediaType

A media type as defined in [RFC6838].

Securing mechanism specifications SHOULD provide integrity protection for any information referenced by a URL that is critical to validation. Mechanisms that can achieve this protection are discussed in Section 5.3 Integrity of Related Resources and Section B.1 Base Context.

A securing mechanism specification that creates a new type of embedded proof MUST specify a property that relates the verifiable credential or verifiable presentation to a proof graph. The requirements on the securing mechanism are as follow:

The securing mechanism MUST define all terms used by the proof graph. For example, the mechanism could define vocabulary specifications and @context files in the same manner as they are used by this specification.

The securing mechanism MUST secure all graphs in the verifiable credential or the verifiable presentation, except for any proof graphs securing the verifiable credential or the verifiable presentation itself.

  Note

The last requirement means that the securing mechanism secures the default graph and, for verifiable presentations, each verifiable credential of the presentation, together with their respective proof graphs. See also Figure 9 or Figure 14.

The proof property as defined in [VC-DATA-INTEGRITY] MAY be used by the embedded securing mechanism.

Securing mechanism specifications SHOULD register the securing mechanism in the Securing Mechanisms section of the Verifiable Credential Extensions document.

    Note: Choice of securing mechanism is use-case dependent

There are multiple acceptable securing mechanisms, and this specification does not mandate any particular securing mechanism for use with verifiable credentials or verifiable presentations. The Working Group that produced this specification did standardize two securing mechanism options, which are: Verifiable Credential Data Integrity 1.0 [VC-DATA-INTEGRITY] and Securing Verifiable Credentials using JOSE and COSE [VC-JOSE-COSE]. Other securing mechanisms that are known to the community can be found in the Securing Mechanisms section of the Verifiable Credential Extensions document.