GAIA-X Service Characteristics
This repository contains schema and documentation for developing compliant Gaia-X Credentials (formerly called Gaia-X Self-Descriptions / SDs).
Credentials ensure the fulfillment of the policies and rules agreed by the participants that decide to build a data ecosystem under the governance defined according to the Gaia-X Association.
To build and validate Credentials, the schema is made available through the Gaia-X Compliance Services.
GitLab Structure
Folders:
- single-point-of-truth
: Single point of truth with respect to Self-Description Schema. Schema contains of a hierarchy of classes, called taxonomy and a set of attributes for each class. Attributes are encoded in YAML files.
- instances
: Sample credentials in JSON-LD.
- toolchain
: Scripts and unit tests for our CI/CD pipeline.
- deprecated
: Files pending to convert to LinkML (eventually will be removed).
Documentation
Markdown is a lightweight markup language which uses a simple and readable syntax. You can find the generated markdown documentation of the LinkML model in the repository's Gitlab Pages.
How to Use the Ontology ?
The Gaia-X ontology has been built with extensibility and mass adoption in mind, so we aim to offer multiple ways of using and extending the ontology.
Using Through w3id.org
To broadcast the Gaia-X ontology schemas, we rely on the perma-id w3id.org project which allows to publish our schemas via a single HTTPS endpoint.
https://w3id.org/gaia-x/
If you resolve the above URL, it will guide you to the Gaia-X ontology documentation; but it has many more features when resolved with a few additional elements which are described in the following chapters.
All the following chapters use a URL with the https://w3id.org/gaia-x/{version}#
pattern where {version}
corresponds
to the version you wish to reference. Then the wanted content type can be specified through the HTTP Accept
request
header.
⚠️ Please note that currently, only
development
is available and it references our latest unstable development version.
SHACL Shapes
The Gaia-X SHACL shapes can be retrieved with the following query:
GET /gaia-x/development# HTTP/1.1
Host: w3id.org
Accept: text/turtle
If you were to extend the Gaia-X SHACL shapes to add mygx:MyLegalPerson
, a child of gx:LegalPerson
, you could use
the following snippet:
@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix gx: <https://w3id.org/gaia-x/development#> .
@prefix mygx: <https://my-gaia-x.eu#> .
gx:MyLegalPersonShape
a gx:LegalPerson ;
sh:closed true ;
sh:description "A custom definition of the Gaia-X LegalPerson" ;
sh:ignoredProperties ( rdf:type ) ;
sh:property [ sh:datatype xsd:string ;
sh:minCount 1 ;
sh:nodeKind sh:Literal ;
sh:order 0 ;
sh:path mygx:myAdditionalAttribute ] ;
sh:targetClass mygx:MyLegalPerson .
✋ We suggest you extends the Gaia-X ontology directly with LinkML as described in the Extending Through LinkML chapter.
JSON-LD Context
The Gaia-X JSON-LD context can be retrieved with the following query:
GET /gaia-x/development# HTTP/1.1
Host: w3id.org
Accept: application/ld+json
Basing ourselves on the example of the SHACL Shapes chapter, a mygx:MyLegalPerson
object would look
like the following example:
{
"@context": {
"gx": "https://w3id.org/gaia-x/development#",
"mygx": "https://my-gaia-x.eu#"
},
"@id": "https://my-gaia-x.eu/myLegalPerson",
"@type": "mygx:MyLegalPerson",
"mygx:myAdditionalAttribute": "Additional Attribute"
}
✋ We suggest you extends the Gaia-X ontology directly with LinkML as described in the Extending Through LinkML chapter.
OWL Ontology
The Gaia-X OWL ontology can be retrieved with the following query:
GET /gaia-x/development# HTTP/1.1
Host: w3id.org
Accept: application/rdf+xml
Extending Through LinkML
The best way to extend the Gaia-X ontology is to use
the powers of LinkML's import
keyword.
In order 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
JavaScript/TypeScript
An NPM package is made available by this repository to allow developers to use Gaia-X entities, shapes and contexts in their JavaScript or TypeScript project.
You can find this package here 👉 https://www.npmjs.com/package/@gaia-x/ontology.
All you need to do is install the Gaia-X ontology NPM package with your favorite dependency management system.
# NPM
npm install --save @gaia-x/ontology
# Yarn
yarn add @gaia-x/ontology
Versions
As NPM package versioning is done with a <major>.<minor>.<patch>
pattern, ontology versions cannot be used.
The below table explains version correspondence.
Ontology version | NPM package version |
---|---|
24.04 | 1.x.x |
How to collaborate
These are the steps you should take if you want to collaborate in the development or maintenance of the working streams that are carried out in the group.
- Check the list of current open issues or create a new one if necessary. You can do it in the issues section.
- Describe the issue and add the appropriate label(s) to it. Be sure of tagging the issue status, especially use
status:in_progress
. - Create a new branch to hold your changes and updates. Name of branch should start with the number of the issue, e.g. 195-governance-process for issue #195.
- Write a YAML file(s) in LinkML format to describe a Gaia-X entity and address your issue ("entity" refers to any good or object of the Gaia-X Ecosystem). Learn how to do it in the Single Point of Truth section.
- Generate, from this LinkML schema, artifacts expressed in terms of commonly used web standards, such a JSON, OWL and SHACL.
At this point, you can get these artifacts in two main ways.
- Create a new merge request to merge your branch to target branch
develop
. This request (also any time you push new changes to your branch) will throw the CI/CD process, that will - among other tasks - generate a zip with these JSON, OWL and SHACL files. - Build these files locally using the LinkML generator tool (*).
(*) Due to some constraints related to current LinkML implementation, the process uses Anja Strunk's fork of LinkML.
Once you got the shapes:
- To check their validity, you need to build and run unit tests. Visit the Unit test section to get more details.
- To validate JSON instances, take a look at the Toolchain section.
When you have all the work done:
- Join our Weekly Meeting to present your request for change to the Sub-Working Group's members and discuss it with them. General information about the group and the links to join can be found at the Member's platform.
- Answer and resolve threads in your Merge Request. Note: Thread may be re-opened by other members.
Guidelines for merge into develop:
- No unresolved thread, no merge conflicts either.
- Successfully run CI/CD pipeline (this process also runs automatically every time you push new changes).
- Presentation of changes in weekly Service Characteristics meeting. The request will require the approval from two members of the group, besides the one from CTO team representative.
- Only merge requests with label
status:ready_for_approval
will be approved and merged.
PLEASE NOTE: The author, this means you, is responsible for propagating relevant changes back to other Gaia-X deliverables. This will not happen automatically or by any other member of the community.
CI/CD
These are the stages that will be executed during the continuous integration process:
- build: build Self-Description artifacts.
- test: test correctness of Self-Descriptions artefacts.
- validate: validate Self-Description samples.
- package: build and publish generated artifacts in package registry.
- pages: publish a Gitlab Pages website
- release: automatically create a new release from a tag.
Ontology Version Management
Gaia-X ontology versions need to be easy to distinguish and reference. To do so, the context name contains the referenced version in its URI.
https://w3id.org/gaia-x/{version}#
For example, this is the URI of the 24.04 Gaia-X ontology namespace.
https://w3id.org/gaia-x/2404#
Please notice that the .
in the version number has been removed for convenience and technical reasons in the URI.
Releasing
For security reasons, only users with a minimum of Maintainer
access level are allowed to create a new release of this project.
Releases are automatically created and published once a tag is created, to do so the following command can be used.
git checkout main
git tag -a v<YOUR_VERSION>
Tags must always be created from the main
branch as it houses production ready code. YOUR_VERSION
must be replaced
with the version you are releasing (ie. 22.10
for October 2022's specification version).
Organization
- All communication is done via Mailing List. Please use the Member's platform to join our group.
- We meet weekly on Friday 08:00-09:00 (Central European (Summer) Time).
- Sources:
- GitLab: source code.
- Gaia-X Members Platform: meeting minutes and binary files.
- Lead: Christoph Lange-Bever, Vice-Lead: Anja Strunk.