Skip to content

Commit

Permalink
chore: align usage of terms and add linkage (#190)
Browse files Browse the repository at this point in the history 
* chore: align dataspace term & add linkage

* chore: align dataspace protocol term

* chore: align dataspace authority term & add linkage

* chore: align dataspace term & add linkage

* chore: align participant term & add linkage

* chore: align participant agent term & add linkage

* chore: align identity provider term & add linkage

* chore: align credential issuer term & add linkage

* chore: add linkage to dataset term

* chore: align policy term & add linkage

* chore: align offer term & add linkage

* chore: align agreement term & add linkage

* chore: align catalog term & add linkage

* chore: align catalog service term & add linkage

* chore: align connector term & add linkage

* chore: align contract negotiation term & add linkage

* chore: align transfer process term & add linkage

* chore: align capitalisation of protocols

* chore: add links to DCAT and ODRL

* chore: fix typos

* chore: resolve missing links for transfer process
  • Loading branch information
@juliapampus
juliapampus authored Dec 17, 2023
1 parent eadbaa0 commit ca29dbf
Show file tree
Hide file tree
Showing 14 changed files with 268 additions and 268 deletions.
42 changes: 21 additions & 21 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,29 +20,29 @@ All changes made to the specification can be reviewed in the [GitHub repository]
## Abstract

The __Dataspace Protocol__ is a set of specifications designed to facilitate interoperable data sharing between entities governed by usage control and based on Web technologies. These specifications
define the schemas and protocols required for entities to publish data, negotiate usage agreements, and access data as part of a federation of technical systems termed a
__*dataspace*__.
define the schemas and protocols required for entities to publish data, negotiate [Agreements](./model/terminology.md#agreement), and access data as part of a federation of technical systems termed a
[Dataspace](./model/terminology.md#dataspace).

## Introduction

Sharing data between autonomous entities requires the provision of metadata to facilitate the transfer of datasets by making use of a data transfer (or application layer) protocol.
Sharing data between autonomous entities requires the provision of metadata to facilitate the transfer of [Datasets](./model/terminology.md#dataset) by making use of a data transfer (or application layer) protocol.
The __Dataspace Protocol__ defines how this metadata is provisioned:

1. How datasets are deployed as [DCAT Catalogs](https://www.w3.org/TR/vocab-dcat-3/) and usage control is expressed as [ODRL Policies](https://www.w3.org/TR/odrl-model/).
2. How contract agreements that govern data usage are syntactically expressed and electronically negotiated.
3. How datasets are accessed using data transfer protocols.
1. How [Datasets](./model/terminology.md#dataset) are deployed as [DCAT Catalogs](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog) and usage control is expressed as [ODRL Policies](https://www.w3.org/TR/odrl-model/).
2. How [Agreements](./model/terminology.md#agreement) that govern data usage are syntactically expressed and electronically negotiated.
3. How [Datasets](./model/terminology.md#dataset) are accessed using Transfer Process Protocols.

These specifications build on protocols located in the [ISO OSI model (ISO/IEC 7498-1:1994)](https://www.iso.org/standard/20269.html) layers, like HTTPS.
The purpose of this specification is to define interactions between systems independent of such protocols, but describing how to implement it in an unambiguous and extensible way.
To do so, the messages that are exchanged during the process are described in this specification and the states and their transitions are specified as state machines, based on the key terms and concepts of a data space.
On this foundation the binding to data transfer protocols, like HTTPS, is described.
To do so, the messages that are exchanged during the process are described in this specification and the states and their transitions are specified as state machines, based on the key terms and concepts of a [Dataspace](./model/terminology.md#dataspace).
On this foundation the binding to Transfer Process Protocols, like HTTPS, is described.

The specifications are organized into the following documents:

* __*Dataspace Model*__ and __*Dataspace Terminology*__ documents that define key terms.
* __*Catalog Protocol*__ and __*Catalog HTTPS Binding*__ documents that define how DCAT Catalogs are published and accessed as HTTPS endpoints respectively.
* __*Contract Negotiation Protocol*__ and __*Contract Negotiation HTTPS Binding*__ documents that define how contract negotiations are conducted and requested via HTTPS endpoints.
* __*Transfer Process Protocol*__ and __*Transfer Process HTTPS Binding*__ documents that define how transfer processes using a given data transfer protocol are governed via HTTPS
* __*Catalog Protocol*__ and __*Catalog HTTPS Binding*__ documents that define how [DCAT Catalogs](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog) are published and accessed as HTTPS endpoints respectively.
* __*Contract Negotiation Protocol*__ and __*Contract Negotiation HTTPS Binding*__ documents that define how [Contract Negotiations](./model/terminology.md#contract-negotiation) are conducted and requested via HTTPS endpoints.
* __*Transfer Process Protocol*__ and __*Transfer Process HTTPS Binding*__ documents that define how [Transfer Processes](./model/terminology.md#transfer-process) using a given data transfer protocol are governed via HTTPS
endpoints.

This specification does not cover the data transfer process as such.
Expand All @@ -51,21 +51,21 @@ As an implication, the data transfer can be conducted in a separated process if

### Context of this specification

The __Dataspace Protocol__ is used in the context of data spaces as described and defined in the subsequent sections with the purpose to support interoperability.
In this context, the specification provides fundamental technical interoperability for participants in data spaces and therefore the protocol specified here is required to join any data space as specified [here]().
Beyond the technical interoperability measures described in this specification, semantic interoperability should also be addressed by the participants. On the perspective of the data space, interoperability needs to be addressed also on the level of trust, on organizational level and on legal level.
The aspect of cross data space communication is not subject of this document, as this is addressed by the data spaces' organizational and legal agreements.
The __Dataspace Protocol__ is used in the context of [Dataspaces](./model/terminology.md#dataspace) as described and defined in the subsequent sections with the purpose to support interoperability.
In this context, the specification provides fundamental technical interoperability for [Participants](./model/terminology.md#participant) in [Dataspaces](./model/terminology.md#dataspace) and therefore the protocol specified here is required to join any [Dataspace](./model/terminology.md#dataspace).
Beyond the technical interoperability measures described in this specification, semantic interoperability should also be addressed by the [Participants](./model/terminology.md#participant). On the perspective of the [Dataspace](./model/terminology.md#dataspace), interoperability needs to be addressed also on the level of trust, on organizational level and on legal level.
The aspect of cross [Dataspace](./model/terminology.md#dataspace) communication is not subject of this document, as this is addressed by the [Dataspaces'](./model/terminology.md#dataspace) organizational and legal agreements.

The interaction of participants in a data space is conducted by the participant agents, so-called Connectors, which implement the protocols described above.
While most interactions take place between Connectors, some interactions with other systems are required.
The interaction of [Participants](./model/terminology.md#participant) in a [Dataspace](./model/terminology.md#dataspace) is conducted by the [Participant Agents](./model/terminology.md#participant-agent), so-called [Connectors](./model/terminology.md#connector--data-service-), which implement the protocols described above.
While most interactions take place between [Connectors](./model/terminology.md#connector--data-service-), some interactions with other systems are required.
The figure below provides an overview on the context of this specification.

An Identity Provider realizes the required interfaces and provides required information to implement Trust Framework of a data space.
The validation of the identity of a given participant agent and the validation of additional claims is the fundamental mechanism. The structure and content of such claims and identity may vary between different data spaces, as well as the structure of such an Identity Provider, e.g. a centralized system, a decentralized system or a federated system.
An [Identity Provider](./model/terminology.md#identity-provider) realizes the required interfaces and provides required information to implement Trust Framework of a [Dataspace](./model/terminology.md#dataspace).
The validation of the identity of a given [Participant Agent](./model/terminology.md#participant-agent) and the validation of additional claims is the fundamental mechanism. The structure and content of such claims and identity may vary between different [Dataspaces](./model/terminology.md#dataspace), as well as the structure of such an Identity Provider, e.g. a centralized system, a decentralized system or a federated system.

A connector will implement additional internal functionalities, like monitoring or Policy Engines, as appropriate. It is not covered by this specification, if a connector implements such or how.
A [Connector](./model/terminology.md#connector--data-service-) will implement additional internal functionalities, like monitoring or policy engines, as appropriate. It is not covered by this specification, if a [Connector](./model/terminology.md#connector--data-service-) implements such or how.

The same applies for the data, which is transferred between the systems. While this document does not define the transport protocol, the structure, syntax and semantics of the data, a specification for those aspects is required and subject to the agreements of the participants or the data space.
The same applies for the data, which is transferred between the systems. While this document does not define the transport protocol, the structure, syntax and semantics of the data, a specification for those aspects is required and subject to the agreements of the [Participants](./model/terminology.md#participant) or the [Dataspace](./model/terminology.md#dataspace).

![Overview on protocol and context](./resources/figures/ProtocolOverview.png)

Expand Down
2 changes: 1 addition & 1 deletion best.practices/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ The Dataspace Protocol is under development and the working group is active on t
The remainder of the document is structured as follows:

* [**Related documents:**](./related.documents.md) provides useful resources for understanding the overarching concepts of **Dataspaces** and other foundational documents.
* [**Related documents:**](./related.documents.md) provides useful resources for understanding the overarching concepts of [Dataspaces](../model/terminology.md#dataspace) and other foundational documents.
* [**Extensions:**](./extensions.md) How to extend the Dataspace Protocol.
* [**Examples:**](./examples.md) Living examples to foster the understanding of the Dataspace Protocol.
* [**How to create Bindings**](./bindings.md)
Expand Down
24 changes: 12 additions & 12 deletions catalog/catalog.binding.https.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,14 @@ The OpenAPI definitions for this specification can be accessed [here](TBD).

### 2.1 Prerequisites

1. The `<base>` notation indicates the base URL for a catalog service endpoint. For example, if the base catalog URL is `api.example.com`, the URL `https://<base>/catalog/request`
1. The `<base>` notation indicates the base URL for a [Catalog Service](../model/terminology.md#catalog-service) endpoint. For example, if the base [Catalog](../model/terminology.md#catalog) URL is `api.example.com`, the URL `https://<base>/catalog/request`
will map to `https//api.example.com/catalog/request`.

2. All request and response messages must use the `application/json` media type.

### 2.2 CatalogError

In the event of a request error, the catalog service must return an appropriate HTTP code and a [CatalogError](./catalog.protocol.md#) in the response body.
In the event of a request error, the [Catalog Service](../model/terminology.md#catalog-service) must return an appropriate HTTP code and a [CatalogError](./catalog.protocol.md#) in the response body.

| Field | Type | Description |
|---------|---------------|-------------------------------------------------------------|
Expand All @@ -42,15 +42,15 @@ Authorization: ...
}
```

The `Authorization` header is optional if the catalog service does not require authorization. If present, the contents of the `Authorization` header are detailed in the
The `Authorization` header is optional if the [Catalog Service](../model/terminology.md#catalog-service) does not require authorization. If present, the contents of the `Authorization` header are detailed in the
[Authorization section](#31-authorization).

The `filter` property is optional. If present, the `filter` property can contain an implementation-specific filter expression or query to be executed as part of the catalog
The `filter` property is optional. If present, the `filter` property can contain an implementation-specific filter expression or query to be executed as part of the [Catalog](../model/terminology.md#catalog)
request.

#### 2.3.2 OK (200) Response

If the request is successful, the catalog service must return a response body containing a [Catalog](./message/catalog.json) which is a profiled DCAT `Catalog` type
If the request is successful, the [Catalog Service](../model/terminology.md#catalog-service) must return a response body containing a [Catalog](./message/catalog.json) which is a profiled [DCAT `Catalog`](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog) type
described by the [Catalog Protocol Specification](catalog.protocol.md).

### 2.4 The `catalog/datasets/{id}` endpoint
Expand All @@ -66,19 +66,19 @@ Authorization: ...
```

The `Authorization` header is optional if the catalog service does not require authorization. If present, the contents of the `Authorization` header are detailed in the
The `Authorization` header is optional if the [Catalog Service](../model/terminology.md#catalog-service) does not require authorization. If present, the contents of the `Authorization` header are detailed in the
[Authorization section](#31-authorization).

#### 2.4.2 OK (200) Response

If the request is successful, the catalog service must return a response body containing a [Dataset](./message/dataset.json) which is a DCAT `Dataset` type
If the request is successful, the [Catalog Service](../model/terminology.md#catalog-service) must return a response body containing a [Dataset](./message/dataset.json) which is a [DCAT `Dataset`](https://www.w3.org/TR/vocab-dcat-3/#Class:Dataset) type
described by the [Catalog Protocol Specification](catalog.protocol.md).

## 3 Technical Considerations

### 3.1 Authorization

A catalog service may require authorization. If the catalog service requires authorization, requests must include an HTTP `Authorization` header with a token. The semantics of
A [Catalog Service](../model/terminology.md#catalog-service) may require authorization. If the [Catalog Service](../model/terminology.md#catalog-service) requires authorization, requests must include an HTTP `Authorization` header with a token. The semantics of
such tokens are not part of this specification.

### 3.2 Versioning
Expand All @@ -87,7 +87,7 @@ such tokens are not part of this specification.

### 3.3 Pagination

A catalog service may paginate the results of a `CatalogRequestMessage`. Pagination data is specified using [Web Linking](https://datatracker.ietf.org/doc/html/rfc5988)
A [Catalog Service](../model/terminology.md#catalog-service) may paginate the results of a `CatalogRequestMessage`. Pagination data is specified using [Web Linking](https://datatracker.ietf.org/doc/html/rfc5988)
and the HTTP `Link` header. The `Link` header will contain URLs for navigating to previous and subsequent results. The following request sequence demonstrates pagination:

```
Expand Down Expand Up @@ -125,18 +125,18 @@ Link: <https://provider.com/catalog?page=2&per_page=100>; rel="previous"

### 3.4 Compression

Catalog services MAY compress responses to a catalog request by setting the `Content-Encoding` header to `gzip` as described in
[Catalog Services](../model/terminology.md#catalog-service) MAY compress responses to a [Catalog](../model/terminology.md#catalog) request by setting the `Content-Encoding` header to `gzip` as described in
the [HTTP 1.1 Specification](https://www.rfc-editor.org/rfc/rfc9110.html#name-gzip-coding).

## 4 The Well-Known Proof Metadata Endpoint

When an implementation supports protected _datasets_, it may offer a proof metadata endpoint clients can use to determine proof requirements. If the implementation
When an implementation supports protected [Datasets](../model/terminology.md#dataset), it may offer a proof metadata endpoint clients can use to determine proof requirements. If the implementation
offers a proof data endpoint, it must use the `dspace-trust` [Well-Known Uniform Resource Identifier](https://www.rfc-editor.org/rfc/rfc8615.html) at the top of the
path hierarchy:

`/.well-known/dspace-trust`

The contents of the response is a JSON object defined by individual trust specifications and not defined here.

Note that if multiple connectors are hosted under the same base URL, a path segment appended to the base well-known URL can be used, for example,
Note that if multiple [Connectors](../model/terminology.md#connector--data-service-) are hosted under the same base URL, a path segment appended to the base well-known URL can be used, for example,
`https://example.com/.well-known/dspace-trust/connector1.`
Loading

0 comments on commit ca29dbf

Please sign in to comment.