RFC047: Respecification of the capabilities endpoint

Background and rationale

The /capabilities endpoint is required for every participant that provides services. The endpoint returns iSHARE capabilities (supported versions & optional features) of the iSHARE party. This way it forms a cornerstone in the technical implementation of the iSHARE Framework.

DSGO is developing a data space for the built environment. The current design of the capabilities object limits its utility within DSGO's data space. Therefore, they recommend modifications for broader generic utility, allowing it to be used in the DSGO and other data spaces.

The DIL programme is developing BDI ("Basis Data Infrastructuur") and is working on implementation in the logistics domain. As part of the programme, Portbase developed a proof of concept. During the proof of concept several possible improvements of the capabilities endpoint have risen.

During the lifetime of iSHARE, new standards have been released. Particularly DCAT version 2 is a relevant standard, which introduced the concept of a Data Service, with a comparable scope as the iSHARE /capabilities endpoint.

Proposed change: purpose

This RFC intends to improve the specification of the capabilities endpoint (more specifically the capabilities_info object) to foster adaptability for data spaces and to improve alignment with new standardisation.

Considerations and requirements

Proposed modifications include:

1 - The "ishare_role" parameter should be renamed to "role" with provision for additional values, accommodating data space-specific roles.

2 - Explicitly allow the expansion of the feature object with extra parameters, facilitating the integration of data space-specific functionalities as necessary.

Description and principles

The following adaptations are foreseen:

  • Loosely base the structure of a capability on the DCAT version 3 class Data Service, building on the work that has been done by DSGO on defining the Data_service_info object.
  • Include a property to refer to a description of the endpoint in OpenAPI format, comparable with the endpoint_description property in the DCAT Data Service class.
  • Restructure the capabilitiesInfo token to a flatter structure by removing the version hierarchy.
  • Rename features to data services, thereby relating to the DCAT Data Service class.

Previously foreseen, but decided to be become part of a separate RFC:

  • Allow the listing of data space specific roles besides iSHARE roles.

Detailed description

The basic structure of the response will be:

  • capabilitiesInfo: object containing publicServices and privateServices
    • publicServices: array containing public services. When no Authorization header is presented when invoking the /capabilities endpoint, only publicServices are returned. PublicServices themselves may (and usually will) require authentication to invoke them.
    • restrictedServices: array containing restricted services. When an Authorization header is presented when invoking the /capabilities endpoint, restricted services may be returned, based on the information provided on the participant by the Authorization header. This could for example be implemented to expose services only to participants of a dataspaces.

The definition of the /capabilities endpoint will be changed so that it will define a response that is in line with the following example response. A more detailed description of the properties of the services is provided here.

{
  "capabilitiesInfo" : {
    "publicServices":[
      {
        "identifier":"", //REQUIRED Free text identifier of the service. Must be unique within the capabilities definition, a URI is preferred. For iSHARE defined services, it must contain the predefined identifier (defined as operationId in the iSHARE generic OpenAPI specification). For other services, it might for instance refer an operationId in OpenAPI specifications, or other forms of identifiers in other specification formats.
        "title":"", //REQUIRED Free text human readable name of the service (the name of this property in the current /capabilities definition is: feature).
        "description": "", //OPTIONAL Free text description of the service (the name of this property in the current /capabilities definition is also: description).
        "descriptionURL":"", //OPTIONAL URL that points to the definition of the service. Could be for instance a URL to an OpenAPI description, a WSDL document, a SPARQL Service Description, a DCAT Data Catalog, etc.
        "endpointURL":"", //REQUIRED URL of the endpoint, including the correct host. Depending on the setup, this information could also already be included in the description that is provided via the descriptionUrl (the name of this property in the current /capabilities definition is: url).
        "tokenEndpoint": "", //OPTIONAL where access token for the feature can be retrieved. This is optional because if the feature is access token, it is not needed to mention it twice (the name of this property in the current /capabilities definition is: p).
        "status":"", //REQUIRED Provides information on the status of the service. Must be either "deprecated" or "active".
        "serviceType": "", //REQUIRED Can be either "framework-defined", "dataspace-defined" or "self-defined". A framework-defined service is required from a framework perspective (including for instance the /capabilities endpoint), a dataspace-defined service is required from a dataspace perspective and a self-defined service is define by the provider of the service (actual data services are part of this category).
        "version": { //REQUIRED
          "compliesWithFrameworkVersions":[], //OPTIONAL array of framework versions that the service complies with, at a framework level. If not included, the service is assumed to be compliant with the latest version. The versions can be retrieved using the /versions endpoint: https://dev.ishare.eu/satellite/versions.html. Required for framework-defined services.
          "compliesWithDataspaceVersions":[], //OPTIONAL array of dataspace versions that the service complies with, at a dataspace level.
          "capabilityVersion":"", //REQUIRED Version of the provided service. The version numbering of services is not related to the version numbering of the framework or of a dataspace.
        },
        "methods":["GET", "POST", ""] //OPTIONAL array of operations supported by the endpoint. It could be HTTP methods when the endpoint is HTTP based, for example: GET, POST, etc.
      }
    ]
  }
}

The following properties have been discussed, but were not added to the capabilities endpoint. The properties will be added as guidance for dataspaces, but will not be part of the official specifications.

{
  "theme":[ //Can be used to link services together into a sequence; expected to be part of a DCAT service description, if available. Decided not to include in the capabilities endpoint as it would complicate it and not solve problems that could not be solved otherwise.
    {
      "title":"",
      "first":"",
      "last":"",
      "previous":"",
      "next":""
    }
  ],
  "license":"", //When a Service Provider is also the Data Owner this could contain the license under which data is provided. Could be part of future improvements.
  "allowedLicenses":[""], //Future idea to filter for licenses (in the delegations) that can be used to invoke the service with
  "mediaType":"", //Does not contribute enough to interoperability to be included as a separate field; would be part of detailed service description in most cases
  "checksum":[ //This will be part of a future topic (possibly RFC) on versioning and framework compliance
    {
      "algorithm":"",
      "checksumValue":""
    }
  ]
}

Impact on the ecosystem

The following table lists the impact of this RFC on the formal iSHARE roles (excluding the Scheme Owner role).

Formal role Technical impact Business / legal / functional / operational impact
Service Consumer Yes No
Service Provider Yes No
Entitled party Yes No
Authorization Registry Yes No
Identity Provider Yes No
Identity Broker Yes No
Data Space Administrator Yes No
Satellite Yes No

Impact iSHARE Foundation (Scheme Owner)

Implementation

Release schedule

These changes will become effective onwards from the version in which the changes are released in. Changes are not backwards compatible.

Communication

Communication about this RFC will be part of the regular communication around framework updates.

Edited by Ángel Rodríguez Fernández