6. Gaia-X Technical Compatibility specifications¶

6.1 Definining 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 defininitions 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 ouf 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, wheres 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 participant identifier is under the control of the credential holder using the verification method bound to the credential.

• The issued identity attributes conform with the KYB/KYC rules associated with the issuance of the identifier.

• 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 this Identifier is under his 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: URI are 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, and 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 as 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. This is done to avoid tampering and to technically allow checking the origin of the claims. The Gaia-X supported verification method is a did:web containing a JSON Web Key. Refer, 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 coming 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 in the Compliance Document

6.6 Gaia-X Credential Format¶

A holder can add 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, which defines the Gaia-X conformity assessment schemes and the requirements for the respective Trust Service Providers.
• the Gaia-X Ontology containing the 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 in order to issue Verifiable Credentials in a secure manner.

It’s a great protocol for machine-to-end-user credential issuance but also from machine-to-machine issuance by using OAuth 2.0’s battle tested and widely adopted standards.

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

⚠️ The current OIDC4VCI 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.2 OpenID Connect for Verifiable Presentations¶

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

This can also be a machine-to-end-user protocol in addition to a machine-to-machine protocol thanks to OAuth 2.0 standards.

Verifiable Presentations will be exchanged by 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 produced or consumed by the Gaia-X Clearing House hence securing the exchange with an authentication and proof of possession mechanism.

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 hasn’t been chosen to this date.

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.

For example, https://w3id.org/gaia-x/{version}#, this is the URI of the 24.11 Gaia-X ontology namespace: 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; uses DCAT as 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 negotiation between participants.

Figure 6.8.3 - Representation of ODRL Model

6.8.4 CAP¶

The Eclipse Conformity Assessment Profile (CAP) Ontology is part of the work of the Eclipse Dataspace Working Group (EDWG). This ontology 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¶

The 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 the form of SHACL shapes (cf. the W3C Shapes Constraint Language SHACL 3 ), a JSON-LD Context and an OWL Ontology. At any point where Credentials are created or received, a Credential forms a data graph. For compliance with Gaia-X and/or specific ecosystem extensions, this data graph must be validated against the given shapes graph according to the SHACL specification. The defined version of the Gaia-X Schema is maintained and made available through the Gaia-X Registry Service.

6.8.5.1 Generation via LinkML¶

LinkML (Linked Modeling Language) 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¶

The provision of services such as Credential storing, Vocabulary services, Authorisation services and Value added services, offered by trusted operators in specific ecosystems, must meet the general requirements for technical compatibility described in this section.

6.9.2 Using Compliance Engine¶

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

• if the digital attestation received is Gaia-X Compliant
• if 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.

Multiple Gaia-X conformity levels exist ranging from Standard Compliance to Gaia-X Label Level 3 depending on the different criteria that have been validated.

Each conformity level has specific criteria that can be shared with other conformity levels, such as defined in the Compliance Document. A filter chain is defined within the Compliance Engine to validate those criteria. Filters can be in charge of validating one to many criteria.

Before going through the filter chain, the input VC-JWT needs to be validated and verified, this 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 all the verifiable credentials each in application/vc+jwt format, describing the participant’s service offering. This input needs to be verified according to the Securing Verifiable Credentials using JOSE and COSE specification.

The JWT headers need to be checked to make sure the content-type and type match the specification. Then the issuer iss and key ID kid headers will be used to collect the DID document and public key. The algorithm used to sign the JWT is stored 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 hasn’t been tampered with. The signature is verified by 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 anchor.

Furthermore, claims are checked to make sure that the JWT is valid time-wise using the exp (expiration date) claim which must be after today’s date as stated in the JWT specification. This claim is optional, so this check is ignored when it is missing from the JWT.

6.9.2.3 Converting to Verifiable Credential List¶

Now that the input Verifiable Presentation has been 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 represents the source of truth for the ecosystem and stores files that are used by the compliance engine.

The following are critical for Gaia-X Lab 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 emit 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 you to check whether your certificate belongs to the trusted anchors and is not revoked.

/api/trusted-issuers

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

6.9.3.1 Gaia-X IPFS Pinning Service¶

The Gaia-X Lab IPFS Pinning Service plays a role in Gaia-X efforts to manage, update, and distribute essential artefacts via the IPFS network. This includes the handling of trust framework schemas and shapes, trusted issuers lists, and revocation lists which are critical for the operation of the Gaia-X Lab Registry Service.

This service utilizes 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, and works 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.

These VCs serve as tangible proof of the registration number’s validity and existence. It’s important to note that while the VC affirms the existence of the registered number, it does not establish a direct association between the credential presenter 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:

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

• A type of the requested legal registration number

• The value of the legal registration number property to verify

Keep in mind that in JSON-LD, the “id” attribute should be resolvable and ideally should lead to the location where you intend to store the Verifiable Credential. This means that the provided id should resolve to the designated storage location for the VC.

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.