4. Verifiable Credential compatibility¶

Credential compatibility is central to technical compatibility.

The criteria in this chapter apply to any Verifiable Credential. They do not assume that the credential was issued within a Gaia-X ecosystem, that it uses the Gaia-X Ontology, or that a registry exists: a credential is assessed against the applicable open standards and against the ontology referenced by its JSON-LD context.

A Verifiable Credential is technically compatible when it:

• is syntactically valid;
• is semantically valid;
• is cryptographically verifiable;
• references the required resolvable resources;
• uses the interoperable formats and mechanisms required by this specification.

This chapter groups the compatibility criteria into six verification groups:

1. VC-1 — the JWT VC signature is verifiable;
2. VC-2 — every DID document referenced by the credential is valid and resolvable (did:web);
3. VC-3 — the credential is a valid VCDM 2.0 credential (SHACL / ontology validation);
4. VC-4 — the credential is valid JSON-LD;
5. VC-5 — the ontology referenced by the credential’s JSON-LD context is resolvable (OWL + JSON-LD);
6. VC-6 — the credential’s terms and values conform to that ontology.

The verification method for every criterion in this chapter is Automated: conformity can be established entirely by a conformant software agent (validator, compliance engine or test suite), based on the artefact under assessment (here: the verifiable credential) and the resources to which it resolves.

Because the criteria are ecosystem-neutral, the primary source cited for each criterion is the open standard that defines the relevant requirement. Where a Gaia-X deliverable adopts or further constrains the corresponding requirement, it is cited after the standard:

1. Architecture Document 3.1
2. ICAM Document 25.11
3. Data Exchange Document 25.07

4.1 VC-1 Check JWT VC signature¶

4.1.1 VC-1.1 VC-JWT encoding¶

The credential shall be encoded as a VC-JWT, with the cryptographic proof constructed using JSON Web Signature (JWS), such that payload, header and signature can be verified for authenticity and integrity.

4.1.2 VC-1.2 Signature algorithm declaration¶

The alg header parameter shall be present and its value shall be a registered algorithm compliant with IETF RFC 7518 (JSON Web Algorithms). The value none shall not be accepted.

Note (informative):
RFC 7518 specifies the following algorthms for the alg parameter:

For more information, consult RFC 7518, Section 3.1

4.1.3 VC-1.3 JSON Web Key as verification method¶

The key material used to verify the signature shall be expressed in the JSON Web Key (JWK) format defined in IETF RFC 7517.

4.1.4 VC-1.4 Signature verification against the resolved key¶

The JWS signature shall verify against the key material resolved from the issuer’s DID document, as designated by the verification method referenced in the JWT header.

4.1.5 VC-1.5 Token validity period¶

Where the exp (expiration date) claim is present, its value shall represent a time later than the time of verification; where the claim is absent, the check shall be skipped. Where the nbf (not before) claim is present, its value shall not represent a time later than the time of verification.

4.2 VC-2 Check validity of all DID documents (did:web)¶

did:web is the DID method used by the compatibility baseline.

4.2.1 VC-2.1 did:web identifiers and HTTPS resolution¶

Every decentralized identifier referenced by the credential — issuer, credential subject, and verification method — shall use the did:web method, shall be syntactically valid, and shall resolve to a DID document over HTTPS.

4.2.2 VC-2.2 DID document well-formedness¶

Each resolved DID document shall be a well-formed DID document as defined by W3C Decentralized Identifiers (DIDs) v1.0, including valid verification methods and valid service entries where present.

4.2.3 VC-2.3 Publication of key material¶

Each resolved DID document shall publish a publicKeyJwk parameter, or reference a jwks_uri that resolves to a JSON Web Key Set (JWKS), for every verification method used by the credential.

4.2.4 VC-2.4 Binding between DID, issuer and signature¶

The verification method used to sign the credential shall be listed in the DID document resolved from the issuer identifier.

4.3 VC-3 Check that the credential is a valid VCDM 2.0 credential (SHACL / ontology)¶

4.3.1 VC-3.1 Verifiable Credentials Data Model conformance¶

The credential shall conform to the W3C Verifiable Credentials Data Model v2.0: required properties shall be present and well-formed, including @context, type, issuer, credentialSubject, and the validity properties where used.

4.3.2 VC-3.2 Validation against a shapes graph, where one is available¶

If a shapes graph applicable to the credential is available, then the credential shall pass validation against this shapes graph according to the SHACL specification.

A shapes graph is published alongside the ontology it applies to, as one of the representations of the ontology IRI, and is requested using HTTP content negotiation as defined in IETF RFC 9110 (HTTP Semantics), Section 12. Its location is therefore not derived from a naming convention, such as a .shacl file next to a .ttl file: the ontology IRI identifies the resource, and the requested media type selects the representation.

The shapes graph is thus discovered from the credential itself: no dedicated credential property and no verifier-specific configuration is involved, and every verifier applies the same shapes graph to the same credential.

If no shapes graph is available, this criterion shall be reported as not applicable and shall not cause the credential to fail; conformance is then established by VC-6 alone.

Note: That means that SHACL validation is optional. But if there exists a shapes graph, the credential has to pass validation against the shapes graph.

4.4 VC-4 Check that the credential is valid JSON-LD¶

4.4.1 VC-4.1 Valid JSON-LD document¶

The credential shall be a valid JSON-LD document: it shall parse as JSON, shall carry a valid @context, and shall expand without error under the JSON-LD expansion algorithm. Expansion shall not discard claims — a term that drops out of the expanded form because it is undefined in the context indicates an invalid credential.

4.5 VC-5 Check that the ontology referenced by the credential’s JSON-LD context is resolvable (OWL + JSON-LD)¶

This group verifies that both the JSON-LD context and the OWL ontology are retrievable: the JSON-LD context maps terms to IRIs, while the OWL ontology defines what those IRIs mean.

4.5.1 VC-5.1 Each @context URL resolves and returns valid JSON-LD¶

Every URL appearing in the credential’s @context shall resolve, and shall return a document that parses as valid JSON-LD.

4.5.2 VC-5.2 The OWL ontology resolves and parses¶

The OWL ontology describing the vocabulary used by the credential shall resolve, and shall parse without syntax errors in the serialization in which it is served — RDF/XML, Turtle, or JSON-LD.

4.6 VC-6 Check the credential against the ontology¶

This group checks the credential’s content against the vocabulary it declares. The three criteria are applied as validation constraints over the credential’s asserted triples, not as RDFS entailment: under RDFS semantics rdfs:domain and rdfs:range infer types rather than reject data, so a reasoner alone would report no violation. They are evaluated in a closed-world manner, and a mismatch is reported as a failure.

4.6.1 VC-6.1 Every term used exists in the ontology¶

Every property and every class used in the credential — after JSON-LD expansion, and excluding the terms defined by the VCDM 2.0 vocabulary itself — shall be declared in the resolved ontology.

4.6.2 VC-6.2 Subject type matches the property’s rdfs:domain¶

For each property asserted in the credential, the asserted type of the subject of that property shall be the class given as the property’s rdfs:domain, or a subclass of it. Where the property declares no rdfs:domain, the check shall be skipped for that property.

4.6.3 VC-6.3 Value type or datatype matches the property’s rdfs:range¶

For each property asserted in the credential, the value shall match the property’s rdfs:range: for an object property, the asserted type of the referenced object shall be the range class or a subclass of it; for a datatype property, the literal’s datatype shall be the declared range datatype. Where the property declares no rdfs:range, the check shall be skipped for that property.

4.7 Summary of criteria¶

A credential that satisfies all applicable criteria in this chapter is eligible for a Proof of Compatibility issued under the conformity assessment scheme Gaia-X Verifiable Credential Compatibility, as described in Proof of compatibility.

Note: ICAM specifications also define or reference optional credential mechanisms. These mechanisms are not assessed by the compatibility criteria in this version. The conditions for their use and the corresponding verification criteria are not yet specified and may be addressed in a future version of this document.