Self-Description Documents

[zeier]

Description

Each dataspace participant including the Dataspace Authority should provide a self-description document.

Self-description documents should eventually be dynamically generated (which is out of scope for this feature) by the IdentityHub based on a given context (e.g., Gaia-X), to provide support for multiple self-description formats.

In a first step, the IdentityHub should provide an endpoint through wich an exemplary self-description document is served. This can be a statically defined self-description document that is served via the IdentityHub API. In subsequent iterations (out of scope for this feature), the implementation can be extended to dynamically generate self-description documents and to support multiple self-description formats.

The IdentityHub will provide the following two endpoints

• Endpoint to retrieve Verifiable Credentials (already implemented, all VCs will be returned)
• Endpoint to retrieve the self-description document

Whiles self-descriptions are an essential aspect of dataspaces, they are currently only provided as an example and not used yet for any specific use case.

There is no specific address that has to be used for self-description, the only requirement currently is that the self-description address can be retrieved from the DID document.

Sample self-description (as of 7.6.2022):

{
    "selfDescription": {
        "@context": {
            "sh": "http://www.w3.org/ns/shacl#",
            "xsd": "http://www.w3.org/2001/XMLSchema#",
            "gx-participant": "http://w3id.org/gaia-x/participant#"        },
        "@type": "gx-participant:LegalPerson",
        "@id": "http://example.org/participant-123456",
        "gx-participant:registrationNumber": {
            "@type": "xsd:string",
            "@value": "DEANY1234NUMBER"        },
        "gx-participant:legalAddress": {
            "@type": "gx-participant:Address",
            "gx-participant:country": {
                "@type": "xsd:string",
                "@value": "FR"            }
        },
        "gx-participant:headquarterAddress": {
            "@type": "gx-participant:Address",
            "gx-participant:country": {
                "@type": "xsd:string",
                "@value": "FR"            }
        }
    },
    "proof": {
        "created": "2022-04-21T15:59:15Z",
        "proofPurpose": "assertionMethod",
        "proofValue": "zGwuJiP42jZq2sMFG8K9t2x9dJX73Ky6pek8pUki6yuDqriQgLUVDxGyVhLY2TNwe656BB4qaZZE5SeqCWeMVxWs",
        "type": "Ed25519Signature2020",
        "verificationMethod": "did:web:vc.gaia-x.eu:issuer#Ed25519VerificationKey2020"    }
}

Acceptance Criteria

• Self-description for the Dataspace Authority can be retrieved from the IdentityHub of the Dataspace Authority.
• Self-descriptions for dataspace participants can be retrieved form the IdentityHub of the dataspace participants.
• DID documents contain the link to the corresponding self-description

Out of Scope

The following points will be needed at a later stage and are out of scope for the current feature.

• Self-descriptions are Gaia-X compliant, i.e. they can be validated against the Gaia-X compliance API
• The IdentityHub endpoint URL to retrieve Verifiable Credentials can be retrieved from the self-description document
• The Dataspace Authority self-description contains the policies to join the DS (expressed on ODRL, specific protocol to be defined)

Stories

• Self-Description ADR IdentityHub#38
• IdentityHub - Self-Description Endpoint IdentityHub#11
• Dataspace Authority Self-Description #19
• Participant Self-Description #186
• DID Documents: Link to Self-Description #187

Context on Gaia-X Compliant Self-Descriptions

A first version of Gaia-X compliant self-descriptions has been implemented in #37, and these self-descriptions at some point need to be integrated in the MVD.

However, Gaia-X compliant self-descriptions are still volatile and work in progress. Gaia-X compliant self-descriptions should therefore be kept in a separate branch for Gaia-X hackathons and only be integrated to the MVD once the corresponding specifications become stable.

The resources below are only included as a reference to the current state of Gaia-X specifications and are not required to complete this feature.

• Gaia-X Service Characteristics
• Gaia-X Yaml Files (single point of truth
• W3C Shapes Constraint Language
• Gaia-X prototype to validate self-descriptions

[marcgs]

• Are there any specs or further reading material related to the self-description?
  • First validated self-description document available (see https://gitlab.com/gaia-x/lab/compliance/gx-compliance/-/merge_requests/10)
• Must self-descriptions be retrievable from the Identity Hub? According to the registration service specs this seems to be the other way around.
  • Both DID Document and the Self-description will contain the IdentityHub URL. This will prevent having to access the Self-description on every IDS request.
• Must or can self-descriptions be publicly available?
  • Self descriptions will be publicly available for the MVD

[marcgs]

Input from Peter Koen: "The Self-Description document will eventually be implemented as Verifiable Presentations coming from the Identity Hub. However, due to the current state of the Gaia-X compliance service we need to provide all Self-Descriptions in a URL to a single .json file. Therefor, we will implement the self description as a static .json file that is located in parallel to the DID in the well-known directory. Let’s call it “self-description.json” for simplicity."

--> This story is no longer needed for MVD.

[zeier]

Reopen as Gaia-X compliant self-descriptions will be required. Clarification required on what's contained in a self-description and how we serve them. During an initial discussion with Peter & Jim we discussed that self-descriptions should eventually be generated based on a given context, and that we will support multiple formats, Gaia-X compliant self-descriptions being one of them. To start with, we could define an IdentityHub endpoint that serves a currently static self-description JSON file. This could then be extended later to dynamically generate self-descriptions.

[zeier]

Discussed during refinement (July 5) that providing statically defined self-description documents (without signed proof and without Gaia-X compliance) is sufficient at the current stage.