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 24.11 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 comprises the 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) (detect stealing VC and replay attack)
• 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 unique attribute that is part of the Participant’s Identity. Each Gaia-X participant provides a unique identifier that is associated with the attributes and the participant can cryptographically prove that the Identifier is under their control. The attributes are evaluated by the 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¶

You can link data from one verifiable credential to another. Using linked data across several VCs can be challenging.

Linking the data only enables the use of IDs that are known and resolvable from within the set of presented VC and always have the claims associated in its credential. This approach can create a huge VP request which can however be managed by using compression algorithms.

Example of two linked Verifiable Credentials:

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

Note: 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 3 components: the subject, the predicate, the object

• each component is an IRI. The object can also be 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 avoid tampering and checking 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¶

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

A Verifiable Presentation contains one or more Verifiable Credentials with individual disclosed claims and 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.

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

Example of Gaia-X Credential Format

Below is the example of a Gaia-X Credential document before becoming a Verifiable Credential:

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

You can find Gaia-X Credentials information in the following documents:

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

6.7 OpenID Connect for Verifiable Credentials¶

OpenID Connect for Verifiable Credentials (OID4VC) is the name for collection of OpenID Connect specifications allowing Verifiable Credential and Verifiable Presentation exchanges.

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

• OpenID Connect for Verifiable Credential Issuance (OIDC4VCI)
• OpenID Connect for Verifiable Presentations (OIDC4VP)

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 is a great protocol for both machine-to-end-user credential issuance and machine-to-machine issuance by leveraging OAuth 2.0’s battle-tested and widely adopted standards.

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

⚠️ The current OIDC4VCI specification is still a draft, which means the implementation may evolve over time. The Gaia-X Lab is headed towards the first approved specification, meanwhile the latest draft will be implemented.

6.7.2 OpenID Connect for Verifiable Presentations¶

Just like OIDC4VCI, OIDC4VP 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 support both machine-to-end-user and machine-to-machine interactions.

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

⚠️ The current OIDC4VP specification is still a draft meaning that the implementation might evolve with time. The Gaia-X Lab is headed towards the first approved specification, meanwhile the latest draft will be implemented.

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 hence 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 a specific solution has not been chosen currently.

6.8 Understanding ontologies¶

The Gaia-X Ontology is built with extensibility and mass adoption in mind.

It offers multiple ways of using and extending the ontology such as,

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

• Extending through LinkML

6.8.1 Versioning¶

The Gaia-X Ontology versions are easy to distinguish and refer to. 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 24.11 version, the specific URI is https://w3id.org/gaia-x/2411#

6.8.2 DCAT¶

The Data Product Catalogue (DCAT) Services are mandatory services that publish Data Product Descriptions (inc. 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 is both machine-readable and easy to maintain.

6.8.5.2 Schema Extensions¶

The best way to extend the Gaia-X ontology is to use the powers of LinkML’s import keyword.

To produce the same mygx:LegalPerson entity as the SHACL Shapes chapter, 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 services, Authorisation services and 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 applies 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 digital attestation is Gaia-X Compliant,
• and whether Labels can be issued.

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 filters 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 are critical for 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 Presentation that are sent to it.

Trust Service Providers

The Registry contains the root certificates of all parties allowed to issue credentials or issue 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 the trusted anchors and has not been revoked.

/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 plays a role in 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 (SPOF) risks 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 Legal Registration Number (LRN) Notary¶

The Gaia-X Legal Registration Number (LRN) notarization service serves 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 notarization 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 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) which 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.