6. Gaia-X Technical Compatibility specifications¶

6.1 Defining Technical Compatibility¶

This document uses the term technical compatibility in the following way:

Our definition is (loosely) derived from the Eclipse Foundation’s usage of the term compatibility in the context of the Eclipse Foundation Specification Process. Be aware, though, that the Eclipse Foundation’s use of the term TCK is slightly different and means both, documented (i.e., written) requirements or testing software.

We stress that this is markedly different from other definitions encountered in the software engineering realm where compatibility often refers to the “ability of two or more systems or components to perform their required functions while sharing the same hardware or software environment “(IEEE) or to the “degree to which a product, system or component can exchange information with other products, systems or components, and/or perform its required functions while sharing the same common environment and resources” (ISO 25010).

We specifically talk about technical compatibility in order to differentiate this form of conformity to a technical specification from the notion of Gaia-X compliance which can be understood as conformity of participants and services to the criteria captured in the Gaia-X Compliance Document (e.g., the 3.0.0 version of the Gaia-X Compliance Document). In line with our separation of the two pillars of our Gaia-X Trust Framework, Gaia-X technical compatibility refers to rule agnostic elements, whereas Gaia-X compliance encompasses the technology agnostic requirements.

The requirements that software components or systems need to demonstrably fulfill are specified in this Chapter of the Architecture Document.

6.2 Understanding Identity and Identifier¶

An Identity is composed of a unique Identifier and an attribute or set of attributes that describe an entity within a given context.

In the Gaia-X context, Identities describe participants (natural persons, companies) and resources (e.g., machines, interconnection or data endpoints) uniquely. An identifier is a unique attribute that is part of the Participant’s identity.

Conditions to trust an identity at the time of the negotiation are:

• The identifiers are under the control of the credential issuer
• The VC signature can be verified
• The VC is cryptographically bound to the credential holder (See key-binding), preventing credential theft and replay attacks.
• The VC issuer strictly conforms to the KYB/KYC rules associated with the verification of the identity.
• The identifier issuers are trustworthy parties based on the Gaia-X Registry and optionally other Verifiable Data Registries that extend the Gaia-X rules.

6.2.1 Using Identifiers in Gaia-X Credentials¶

An identifier is a language-independent label, sign or token that uniquely identifies a Participant (cf. prEN 18235-3 Trusted Data Transactions - Part 3: Interoperability Requirements). Each Gaia-X Participant provides a self-chosen unique identifier (did:web) with cryptographic prove that the chosen identifier is really under their control (e.g., this is established through the EV SSL validation process by an external third party). The identifier is then used to strongly associate several attributes with the participant (e.g., country of origin of its head quarters). These attributes, in turn, are evaluated by (other) Participants to implement, enforce, and monitor permissions, prohibitions and duties when negotiating a contract for services or resources.

Each of the following MUST have a unique identifier:

• a Verifiable Presentation

• a Verifiable Credential

• the subject of a Verifiable Credential

6.3 Using Linked Data¶

Linked Data can be used to reference information contained in other Verifiable Credentials.

Linking the data only enables the use of IDs that are known and resolvable within the set of presented VC and always have the claims associated in its credential. This approach can result in large VP requests, which can be managed using compression algorithms.

Example of two linked Verifiable Credentials:

When a verifier requests VC1, the holder should embed in VP1 all VCs referred to in VC1’s credentialSubject object, recursively, i.e., VC2.

Note: A Uniform Resource Identifier (URI) is not necessarily resolvable.

{
  "@id": "https://example.com/VP1",
  "verifiableCredential": [
    {
      "@id": "https://example.com/VC1",
      "credentialSubject": {
        "@id": "https://example.com/VC1/CS1",
        "hasProperty": {"@id": "VC2/CS1"}
      }
    },
    {
      "@id": "https://example.com/VC2",
      "credentialSubject": {
        "@id": "https://example.com/VC2/CS1"
      }
    }
  ]
}

The Linked Data principles and RDF data model’s core concepts are:

• the structure of the information is a set of RDF triples called an RDF graph

• each RDF triple consists of three components: subject, predicate, and object

• each component is an IRI (which is an URI allowing arbitrary unicode charaters and not just a subset of US-ASCII as an URI). The object can also be a literal.

6.4 Using Verifiable Credentials¶

A credential is a set of one or more claims made by the same entity. Credentials might also include an identifier and metadata to describe properties of the credential, such as the issuer, the validity date and time period, a representative image, verification material, status information, and so on.

A verifiable credential is a set of tamper-evident claims and metadata that cryptographically prove who issued it. Examples of verifiable credentials include, but are not limited to, digital employee identification cards, digital driver’s licenses, or digital educational certificates.

Gaia-X Credentials are Verifiable Credentials containing claims using the Gaia-X Ontology in specific context. Claims are expressed in Resource Description Framework (RDF).

Claims validation can be performed either by using publicly available open data and performing tests or using data from Trusted Data Sources. The underlying trust is then provided by Ecosystem Credentials.

VCs are used to share and exchange information between entities. VCs are managed via a wallet, a registry or an agent service run by the holder or by a party the holder has delegated rights to, called custodian wallet.

A Verifiable Credential includes:

• Metadata

• A subject

• A list of claims

• A list of evidence

• Verifiable proof

{
  "@context": [
    "https://www.w3.org/2018/credentials/v2",
    "https://w3id.org/gaia-x/development#"
  ],
  "@type": [
    "VerifiableCredential",
    "LegalParticipant"
  ],
  "@id": "https://example.org/legal-participant/68a5bbea9518e7e2ac1cc75bcc8819a7edd5c4711e073ffa4bb260034dc6423c/data.json",
  "issuer": "did:web:example.org",
  "validFrom": "2024-04-01T12:26:22.601516+00:00",
  "validUntil": "2024-01-01T12:26:22.601516+00:00",
  "credentialSubject": {
    "id": "https://example.org/legal-participant-json/68a5bbea9518e7e2ac1cc75bcc8819a7edd5c4711e073ffa4bb260034dc6423c/data.json",
    "type": "gx:LegalPerson",
    "gx:legalName": "Example Org",
    "gx:legalRegistrationNumber": {
      "id": "https://example.org/gaiax-legal-registration-number/68a5bbea9518e7e2ac1cc75bcc8819a7edd5c4711e073ffa4bb260034dc6423c/data.json"
    },
    "gx:headquarterAddress": {
      "gx:countrySubdivisionCode": "FR-75"
    },
    "gx:legalAddress": {
      "gx:countrySubdivisionCode": "FR-75"
    }
  }
}

6.5 Verifying Gaia-X Credentials¶

To ensure a Gaia-X Credential’s integrity and authenticity, its claims MUST be cryptographically signed by the Issuer to prevent tampering and enable verification of the origin of the claims. The Gaia-X supported verification method is a did:web containing a JSON Web Key. See W3C JSON Web Key.

A Verifiable Credential is Gaia-X Compliant if:

• it is signed by a trusted issuer present in the Gaia-X Registry

• its issuer has a verifiable identity from one of the Trust Service Providers

• it complies with the Gaia-X Ontology SHACL Shapes

• it uses the cryptographic proof mechanism specified in the ICAM document

• it follows the rules specified in the Compliance Document

6.6 Gaia-X Credential Format¶

This section extends the W3C Verifiable Credentials Data Model v2.0 to specify how it shall be applied in the scope of Gaia-X.

A holder can combine several Gaia-X credentials to build a Verifiable Presentation (VP).

A Verifiable Presentation contains one or more Verifiable Credentials with individually disclosed claims, packaged in such a way that the authorship of the data is verifiable. It SHOULD be extremely short-lived, and bound to a challenge provided by a verifier. Each Verifiable Credential that might have been issued by multiple issuers contains signed claims about one or more subjects.

Example of Gaia-X Credential Format

An example of a Gaia-X Credential document before becoming a Verifiable Credential is provided below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://w3id.org/gaia-x/development#"
  ],
  "@type": [
    "VerifiableCredential",
    "LegalPerson"
  ],
  "@id": "https://example.org/legal-participant/68a5bbea9518e7e2ac1cc75bcc8819a7edd5c4711e073ffa4bb260034dc6423c/data.json",
  "issuer": "did:web:example.org",
  "validFrom": "2024-01-01T12:26:22.601516+00:00",
  "validUntil": "2024-04-01T12:26:22.601516+00:00",
  "credentialSubject": {
    "id": "https://example.org/legal-participant-json/68a5bbea9518e7e2ac1cc75bcc8819a7edd5c4711e073ffa4bb260034dc6423c/data.json",
    "type": "gx:LegalPerson",
    "gx:legalName": "Example Org",
    "gx:legalRegistrationNumber": {
      "id": "https://example.org/gaiax-legal-registration-number/68a5bbea9518e7e2ac1cc75bcc8819a7edd5c4711e073ffa4bb260034dc6423c/data.json"
    },
    "gx:headquarterAddress": {
      "gx:countrySubdivisionCode": "FR-75"
    },
    "gx:legalAddress": {
      "gx:countrySubdivisionCode": "FR-75"
    }
  }
}

Additional information on Gaia-X Credentials can be found in the following documents:

• the Gaia-X Compliance Document, which defines the Gaia-X conformity assessment schemes and the requirements for the respective Trust Service Providers.
• the Gaia-X Ontology, which contains the models used to support the automation of Gaia-X Compliance.

6.7 OpenID Connect for Verifiable Credentials¶

OpenID Connect for Verifiable Credentials (OID4VC) is a collection of OpenID Connect specifications allowing the exchange of Verifiable Credentials and Verifiable Presentations.

The two main specifications that are relevant in the Gaia-X Ecosystem are:

• OpenID Connect for Verifiable Credential Issuance (OID4VCI)
• OpenID Connect for Verifiable Presentations (OID4VP)

6.7.1 OpenID Connect for Verifiable Credential Issuance¶

This specification is based on the OAuth 2.0 specification and allows an issuer to communicate with a holder and its wallet to issue Verifiable Credentials in a secure manner.

It supports both machine-to-end-user credential issuance and machine-to-machine issuance as it leverages OAuth 2.0’s battle-tested and widely adopted standards.

Verifiable Credentials will be exchanged using the VC-JWT format.

✅ The OID4VCI specification has reached its first approved version. The Gaia-X Lab implements OID4VCI v1.0 final, using the pre-authorized code flow: the issuer generates a credential offer, the wallet exchanges the pre-authorized code for an access token, and then requests the credential.

6.7.2 OpenID Connect for Verifiable Presentations¶

Just like OID4VCI, OID4VP is based on the OAuth 2.0 specification to allow a holder and its wallet to present one or multiple Verifiable Credentials to a verifier through a Verifiable Presentation.

As per OAuth 2.0 standards, this protocol supports both machine-to-end-user and machine-to-machine interactions.

Verifiable Presentations will be exchanged using the VC-JWT format.

✅ The OID4VP specification has reached its first approved version. The Gaia-X Lab implements OID4VP v1.0 final, which uses a DCQL query to request credentials and the did client identifier scheme so the wallet can verify the signed Authorization Request against the verifier’s DID document.

6.7.3 Usage¶

Both these protocols will be used each time a Verifiable Credential needs to be issued or consumed by the Gaia-X Clearing House, thereby securing the exchange through authentication and proof-of-possession mechanisms.

6.7.4 Cloud/Enterprise Wallet¶

As most of the exchanges will be in a machine-to-machine environment, a cloud or enterprise wallet will be used, although no specific solution has yet been selected.

6.8 Gaia-X Ontology¶

The Gaia-X Ontology is designed with extensibility and interoperability in mind.

It offers multiple ways to use and extend the ontology:

• Using the ontology through w3id.org - SHACL shapes, JSON-LD Context and OWL Ontology can be retrieved by using specific queries

• Extending the ontology through LinkML

6.8.1 Versioning¶

The Gaia-X Ontology versions are easy to identify and reference. To do so, the context name contains the referenced version in its URI.

The Gaia-X Ontology namespace follows this URI pattern: https://w3id.org/gaia-x/{version}#. For the 2.1.11 version, the specific URI is https://w3id.org/gaia-x/v2111

6.8.2 DCAT¶

The Data Product Catalogue (DCAT) Services are mandatory services that publish Data Product Descriptions (including metadata) and support search functionality. They use DCAT as the core protocol for Data Product description.

Data Catalog Vocabulary allows publication and discovery of catalogues with defined vocabularies.

6.8.3 ODRL¶

The Open Digital Rights language (ODRL) allows to express policies that can be evaluated for access and usage control or in contract negotiations between participants.

Figure 6.8.3 - Representation of ODRL Model

6.8.4 CAP¶

The Eclipse Conformity Assessment Profile (CAP) Ontology developed within the Eclipse Dataspace Working Group (EDWG), provides a standardized framework for expressing and verifying conformity assessment policies, leveraging verifiable credentials and aligning with ISO/IEC 17000:2020 standards. By defining key concepts such as certifications, attestations, evidence, and requirements, CAP enhances interoperability and trust in data sharing ecosystems.

6.8.5 Gaia-X Schema¶

Gaia-X members define the Schema for Gaia-X Credentials. It is used as the vocabulary of the claims about credential subjects and must be available in three formats: * SHACL shapes (cf. the W3C Shapes Constraint Language SHACL 3 ) * JSON-LD Context, and * OWL Ontology.

Whenever Credentials are created or received, they form a data graph. To ensure compliance with Gaia-X and/or specific ecosystem extensions, this data graph must be validated against the given SHACL shapes graph according to the SHACL specification. The current version of the Gaia-X Schema is maintained and is available through the Gaia-X Registry Service.

6.8.5.1 Generation via LinkML¶

Linked Modeling Language (LinkML) is a modeling language designed to define data schemas that can be used across a wide range of formats and technologies. It enables the creation of a single, platform-independent source of truth that can be automatically transformed into multiple serializations, including JSON-LD, OWL, SHACL, Python, and TypeScript.

By defining classes, properties, constraints, and relationships in a LinkML YAML schema, members can generate semantic web artifacts like OWL for ontological reasoning or SHACL for data validation. Additionally, JSON-LD outputs facilitate integration with linked data systems. This multi-target capability allows to maintain consistency across data modeling, validation, documentation, and code generation workflows.

As a result, LinkML streamlines the process of creating interoperable, semantically-consistent data models which are both machine-readable and easy to maintain.

6.8.5.2 Schema Extensions¶

The Gaia-X ontology extensions can be implemented using LinkML’s import keyword.

To produce the same mygx:LegalPerson entity as defined in the SHACL Shapes section, the following LinkML snippet can be used:

id: https://my-gaia-x.eu#my-ontology
name: my-ontology
default_prefix: mygx
prefixes:
  gaia-x: https://w3id.org/gaia-x/development/linkml/
  mygx: https://my-gaia-x.eu#
imports:
  - gaia-x:types
classes:
  MyLegalPerson:
  title: "My Legal Person"
  is_a: LegalPerson
  description: A custom definition of the Gaia-X LegalPerson

6.9 Managing Trust Services¶

6.9.1 Trusted Service Operators¶

Services such as Credential storage, vocabulary, authorisation, and other value-added services, when provided by trusted operators within specific ecosystems, must comply with the general requirements for technical compatibility described in this section.

6.9.2 Using Compliance Engine¶

The Gaia-X Compliance engine implements the rules defined in the Gaia-X Compliance Document from high level objectives to low level requirements. It performs checks to determine:

• whether the received Verifiable Presentation is Gaia-X Compliant,
• and whether a Gaia-X Compliance credential can be issued and at which conformity level.

The Gaia-X Compliance Engine is the main Gaia-X Digital Clearing House entry point. It exposes REST endpoints that allow participants to obtain a Gaia-X Compliance credential by submitting credentials describing themselves and the service offerings they provide.

Several levels of Gaia-X conformity exist, from Standard Compliance to Gaia-X Label Level 3 depending on the criteria that have been validated.

Each conformity level has specific criteria, some of which may be shared across levels, as defined in the Compliance Document. A filter chain is defined within the Compliance Engine to validate these criteria. Each filter may be responsible for validating one or multiple criteria.

Before going through the filter chain, the input VC-JWT (Verifiable Credentail - JSON Web Tokens) must be validated and verified. This process is explained in the next chapter.

6.9.2.1 Checking JWT Headers¶

The input of the Compliance Engine is a verifiable presentation in application/vp+jwt format containing multiple verifiable credentials each in application/vc+jwt format, describing the participant’s service offering. This input must be verified according to the Securing Verifiable Credentials using JOSE and COSE specification.

The JWT headers must be checked to ensure the content-type and type fields conform to the specification. Next, the issuer iss and key ID kid headers are used to retrieve the corresponding DID document and public key. The algorithm used to sign the JWT is indicated in the alg header.

{
  "alg": "ES256",
  "typ": "vp+jwt",
  "cty": "vp",
  "iss": "did:web:gaia-x.eu",
  "kid": "did:web:gaia-x.eu#key-0"
}

6.9.2.2 Verifying and Decoding JWT¶

Using the previously extracted headers, the JWT can be decoded and verified using any widely used JOSE library.

During the verification process, the JWT signature is checked to ensure that the content of the payload is not tampered. The signature is verified using the issuer’s public key from the verification method of the DID document in conjunction with the signing algorithm to make sure the JWT was signed with the issuer’s matching private key. This enforces non-repudiation of the Compliance Engine input.

The aforementioned verification method in the kid retrieved from the DID document must also contain a certificate delivered from a Trust Service Provider.

Furthermore, claims are checked to make sure that the JWT is valid regarding the validity period using the exp (expiration date) claim. This value must be later than the current date as stated in the JWT specification. Since the claim is optional, this check is skipped if the claim is not present in the JWT.

6.9.2.3 Converting to Verifiable Credential List¶

Once the input Verifiable Presentation is verified, its content can be converted from a list of Enveloped Verifiable Credentials to a list of Verifiable Credentials that can be passed through the filter chain.

6.9.3 Using the Registry¶

The Gaia-X Registry is one of the mandatory components to perform compliance checks. It acts as the source of truth for the ecosystem and stores the files used by the compliance engine.

The following elements are critical for the Gaia-X Registry Service:

Shapes

The registry serves the shapes that are used by the compliance engine to ensure the validity of the structure of the Verifiable Presentations that are sent to it.

Trust Service Providers

The Registry contains the root certificates of all parties allowed to issue credentials or sub-certificates based on the trust framework.

The Registry also contains the list of TSPs approved for a particular scope.

Currently, it contains the list of eIDAS national trust service providers as well as the list of accredited EV-SSL certificates issuers from Mozilla Certificate Authority Store.

Revocation lists

To exclude a malicious actor, the registry contains a list of revoked certificates.

Provided APIs

/api/trustAnchor

The endpoint allows to check whether a certificate belongs to a trust anchor and has not been revoked.

References to the term Trust Anchor will be updated in the document once the corresponding changes are included in a software release.

/api/trusted-issuers

The endpoint exposes the list of accredited credentials issuers for Gaia-X credentials, e.g. the Gaia-X Digital Clearing House (GXDCH).

6.9.3.1 Gaia-X IPFS Pinning Service¶

The Gaia-X IPFS Pinning Service supports Gaia-X efforts to manage, update, and distribute essential artefacts via the IPFS network. These artefacts includes trust framework schemas and shapes, trusted issuers lists, and revocation lists. These elements are critical for the operation of the Gaia-X Registry Service.

This service uses DNS TXT records to broadcast the root content ID, which is an addressable hash in IPFS, to GXDCHs. It is used to publish, share and update artefacts, across the ecosystem and specifically with Gaia-X registries that are also encouraged to seed their files through IPFS to other GXDCHs and the broader community.

Using IPFS as a storage layer for the registry helps eliminate single points of failure (SPOFs) by distributing data across a decentralized network, ensuring high availability and resilience. It also provides content-addressable storage, which guarantees data integrity and verifiability, fostering a secure and reliable network.

6.9.4 Using the Gaia-X Legal Registration Number (LRN) Notary¶

The Gaia-X Legal Registration Number (LRN) notarisation service plays a crucial role in validating legal registration numbers. Its primary function is to verify the authenticity and existence of the registration numbers provided and subsequently issue signed Verifiable Credentials.

The VCs serve as tangible proof of the registration number’s validity and existence. It is important to note that while the VC affirms the existence of the registered number, it does not establish a direct association between the credential holder and the respective company. This is because the verification process allows anyone to confirm the validity of a registration number, making it a valuable tool for various purposes.

The Gaia-X LRN (Legal Registration Number) service focuses on three specific types of legal registration numbers, namely VAT ID, EORI, LEI code, and potentially a TAX ID. These are key identifiers used in the business and legal domains. When entities present these numbers for verification, the Gaia-X LRN notarization service confirms their existence, providing a level of trust and reliability to these critical identifiers.

Example of a VC issued by a notary:

The Notary exposes an API endpoint(s) that require as input:

• The vcid and subjectId, which will be used respectively as a credential ID and as credential subject ID in the Verifiable Credential response

• The type of the requested legal registration number

• The value of the legal registration number property to verify

If the legal registration number is valid, you will receive a Verifiable Credential. This VC serves as tangible proof of the number’s authenticity and existence, enhancing trust and reliability. If the provided number is not valid, the API will return an HTTP error with a message.