Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: align asset/dataset terminology #189

Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,12 +25,12 @@ __*dataspace*__.

## Introduction

Sharing data between autonomous entities requires the provision of metadata to facilitate the transfer of assets 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 by making use of a data transfer (or application layer) protocol.
The __Dataspace Protocol__ defines how this metadata is provisioned:

1. How data assets 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/).
1. How data 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/).
juliapampus marked this conversation as resolved.
Show resolved Hide resolved
2. How contract agreements that govern data usage are syntactically expressed and electronically negotiated.
3. How data assets are accessed using data transfer protocols.
3. How datasets are accessed using data transfer 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.
Expand Down
26 changes: 13 additions & 13 deletions catalog/catalog.protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ This document outlines the catalog protocol. The following terms are used:

- A _**message type**_ defines the structure of a _message_.
- A _**message**_ is an instantiation of a _message type_.
- A _**catalog**_ is a [DCAT catalog](https://www.w3.org/TR/vocab-dcat-3/) offered by a _provider_
- a _**catalog service**_ is a provider participant agent that advertises offered assets
- A _**consumer**_ is a participant agent that requests access to an offered asset.
- A _**catalog**_ is a [DCAT catalog](https://www.w3.org/TR/vocab-dcat-3/) offered by a _provider_.
- a _**catalog service**_ is a provider participant agent that advertises offered datasets.
- A _**consumer**_ is a participant agent that requests access to an offered datasets.

The catalog protocol defines a how a `Catalog` is requested from a catalog service by a consumer using an abstract message exchange format. The concrete message exchange wire
format is defined in binding specifications.
Expand Down Expand Up @@ -56,7 +56,7 @@ be defined in the relevant catalog binding specification.

#### Description

The catalog contains all [Asset Entries](#31-asset-entry) which the requester shall see.
The catalog contains all [Datasets](#31-dataset) which the requester shall see.


### 2.3 CatalogError
Expand Down Expand Up @@ -112,24 +112,24 @@ The catalog service may require an authorization token. Details for including th

This section describes how the IDS Information Model maps to DCAT resources.

### 3.1 Asset Entry
### 3.1 Dataset

An `Asset Entry` is a [DCAT Dataset](https://www.w3.org/TR/vocab-dcat-3/#Class:Dataset) with the following attributes:
A `Dataset` is a [DCAT Dataset](https://www.w3.org/TR/vocab-dcat-3/#Class:Dataset) with the following attributes:

#### 3.1.1 odrl:hasPolicy

An asset entry Dataset must have 1..N `hasPolicy` attributes that contain an ODRL `Offer` defining the usage control policy associated with the asset. Offers must NOT contain any
target attributes. The target of an offer is the asset associated with the containing asset entry.
A `Dataset` must have 1..N `hasPolicy` attributes that contain an ODRL `Offer` defining the usage control policy associated with the dataset. Offers must NOT contain any
target attributes. The target of an offer is the associated dataset.

> Note: As `odrl:hasPolicy rdfs:domain odrl:Asset` and `AssetEntry isA dcat:Dataset`, each `Asset Entry` is also an `odrl:Asset` from an ODRL perspective.
> Note: As `odrl:hasPolicy rdfs:domain odrl:Asset` and `dspace:Dataset isA dcat:Dataset`, each `Dataset` is also an `odrl:Asset` from an ODRL perspective.
juliapampus marked this conversation as resolved.
Show resolved Hide resolved

### 3.2 Distributions

An asset may contain 0..N [DCAT Distributions](https://www.w3.org/TR/vocab-dcat-3/#Class:Distribution). Each distribution must have at least one `DataService` which specifies where
the distribution is obtained. Specifically, a `DataService` specifies the endpoint for initiating a `ContractNegotiation` and `AssetTransfer`.
A dataset may contain 0..N [DCAT Distributions](https://www.w3.org/TR/vocab-dcat-3/#Class:Distribution). Each distribution must have at least one `DataService` which specifies where
the distribution is obtained. Specifically, a `DataService` specifies the endpoint for initiating a `ContractNegotiation` and `TransferProcess`.

A Distribution may have 0..N `hasPolicy` attributes that contain an ODRL `Offer` defining the usage control policy associated with the asset and this explicit `Distribution`.
Offers must NOT contain any target attributes. The target of an offer is the asset entry that contains the distribution.
A Distribution may have 0..N `hasPolicy` attributes that contain an ODRL `Offer` defining the usage control policy associated with the dataset and this explicit `Distribution`.
Offers must NOT contain any target attributes. The target of an offer is the dataset that contains the distribution.

Support for `hasPolicy` attributes on a `Distribution` is optional. Implementations may choose not to support this feature, in which case they should return an appropriate error
message to clients.
Expand Down
6 changes: 3 additions & 3 deletions catalog/message/example/dcat.distribution.example.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@
"@context": "https://w3id.org/dspace/v0.8/context.json",
"@id": "http://provider.com/catalog1/dataset1/",
"@type": "dcat:Dataset",
"dct:title": "IDS Dataset #1",
"dct:title": "Dataset #1",
"dct:description": [
{
"@language": "en",
"@value": "This is the number 1 data asset of the IDS. The consumer must be a TRUST_PLUS certified connector."
"@value": "This is the number 1 dataset. The consumer must be a TRUST_PLUS certified connector."
},
{
"@language": "de",
"@value": "Dies ist das Nummer 1 Data Asset im IDS. Der Consumer muss ein TRUST_PLUS zertifizierter Connector sein."
"@value": "Dies ist das Nummer 1 dataset. Der Consumer muss ein TRUST_PLUS zertifizierter Connector sein."
}
],
"dcat:keyword": [
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,19 @@
"@context": "https://w3id.org/dspace/v0.8/context.json",
"@id": "http://provider.com/catalog1/dataset1/",
"@type": "dcat:Dataset",
"dct:title": "IDS Dataset Collection",
"dct:title": "Dataset Collection",
"dct:description": [
{
"@language": "en",
"@value": "This dataset includes all assets which identifiers comply to the pattern 'urn:guid:[A-F0-9]{8}\\-[A-F0-9]{4}\\-[A-F0-9]{4}\\-[A-F0-9]{4}\\-[A-F0-9]{12}'. A download via a S3 transfer costs 5 EUR, while the HTTP_REST transfer option costs only 2 EUR. The consumer must be a TRUST_PLUS certfified connector. No further distribution is allowed."
"@value": "This dataset includes all datasets which identifiers comply to the pattern 'urn:guid:[A-F0-9]{8}\\-[A-F0-9]{4}\\-[A-F0-9]{4}\\-[A-F0-9]{4}\\-[A-F0-9]{12}'. A download via a S3 transfer costs 5 EUR, while the HTTP_REST transfer option costs only 2 EUR. The consumer must be a TRUST_PLUS certfified connector. No further distribution is allowed."
},
{
"@language": "de",
"@value": "Dieses Dataset bezeichnet alle Assets, deren Identifier dem Pattern 'urn:guid:[A-F0-9]{8}\\-[A-F0-9]{4}\\-[A-F0-9]{4}\\-[A-F0-9]{4}\\-[A-F0-9]{12}' folgen. Ein Transfer via S3 kostet etwa 5 Euro, wohingegen der Transfer via HTTP_RESt nur mit etwa 2 Euro zu Buche schlägt. Der Consumer muss ein TRUST_PLUS zertifizierter Connetor sein. Eine Weiterverbreitung ist nicht gestattet."
"@value": "Dieses Dataset bezeichnet alle Datasets, deren Identifier dem Pattern 'urn:guid:[A-F0-9]{8}\\-[A-F0-9]{4}\\-[A-F0-9]{4}\\-[A-F0-9]{4}\\-[A-F0-9]{12}' folgen. Ein Transfer via S3 kostet etwa 5 Euro, wohingegen der Transfer via HTTP_RESt nur mit etwa 2 Euro zu Buche schlägt. Der Consumer muss ein TRUST_PLUS zertifizierter Connetor sein. Eine Weiterverbreitung ist nicht gestattet."
}
],
"dcat:keyword": [
"data space",
"data asset",
"dcat dataset",
"collection"
],
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,19 @@
"@context": "https://w3id.org/dspace/v0.8/context.json",
"@id": "http://provider.com/catalog1/dataset1/",
"@type": "dcat:Dataset",
"dct:title": "IDS Dataset Collection",
"dct:title": "Dataset Collection",
"dct:description": [
{
"@language": "en",
"@value": "This dataset includes all assets which identifiers comply to the pattern 'urn\\:guid\\:[A-F0-9]{8}\\-[A-F0-9]{4}\\-[A-F0-9]{4}\\-[A-F0-9]{4}\\-[A-F0-9]{12}'. A download via an S3 transfer costs 5 EUR, while the HTTP_REST transfer option costs only 2 EUR. The consumer must be a TRUST_PLUS certfified connector. No further distribution is allowed."
"@value": "This dataset includes all datasets which identifiers comply to the pattern 'urn\\:guid\\:[A-F0-9]{8}\\-[A-F0-9]{4}\\-[A-F0-9]{4}\\-[A-F0-9]{4}\\-[A-F0-9]{12}'. A download via an S3 transfer costs 5 EUR, while the HTTP_REST transfer option costs only 2 EUR. The consumer must be a TRUST_PLUS certfified connector. No further distribution is allowed."
},
{
"@language": "de",
"@value": "Dieses Dataset bezeichnet alle Assets, deren Identifier dem Pattern 'urn:guid:[A-F0-9]{8}\\-[A-F0-9]{4}\\-[A-F0-9]{4}\\-[A-F0-9]{4}\\-[A-F0-9]{12}' folgen. Ein Transfer via S3 kostet etwa 5 Euro, wohingegen der Transfer via HTTP_RESt nur mit etwa 2 Euro zu Buche schlägt.. Der Consumer muss ein TRUST_PLUS zertifizierter Connetor sein. Eine Weiterverbreitung ist nicht gestattet."
"@value": "Dieses Dataset bezeichnet alle Datasets, deren Identifier dem Pattern 'urn:guid:[A-F0-9]{8}\\-[A-F0-9]{4}\\-[A-F0-9]{4}\\-[A-F0-9]{4}\\-[A-F0-9]{12}' folgen. Ein Transfer via S3 kostet etwa 5 Euro, wohingegen der Transfer via HTTP_RESt nur mit etwa 2 Euro zu Buche schlägt.. Der Consumer muss ein TRUST_PLUS zertifizierter Connetor sein. Eine Weiterverbreitung ist nicht gestattet."
}
],
"dcat:keyword": [
"data space",
"data asset",
"dcat dataset",
"collection"
],
Expand Down
34 changes: 17 additions & 17 deletions model/model.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,24 +16,24 @@ Note that all relationships are multiplicities unless specified.
Dataspace Authority may require participants to obtain some form of business certification. A Dataspace authority may also impose technical requirements such as support for the
technical enforcement of specific usage policies.
- A `Participant` is a member of one or more `Dataspaces`. A participant registers `Participant Agents` that perform tasks on its behalf.
- A `Participant Agent` performs tasks such as publishing a catalog or engaging in an asset transfer. In order to accomplish these tasks, a participant agent may
- A `Participant Agent` performs tasks such as publishing a catalog or engaging in a dataset transfer. In order to accomplish these tasks, a participant agent may
use a _**verifiable presentation**_ generated from a _**credential**_ obtained from a third-party issuer. A participant agent may also use an _**ID token**_ issued by a
third-party identity provider. Note that a participant agent is a logical construct and does not necessarily correspond to a single runtime process.
- An `Identity Provider` is a trust anchor that generates `ID tokens` used to verify the identity of a `Participant Agent`. Multiple identity providers may operate in
a dataspace. The types and semantics of ID tokens are not part of this specification. An identity provider may be a third-party or a participant itself (for example, in the case
of decentralized identifiers).
- A `Credential Issuer` issues _verifiable credentials_ used by participant agents to allow access to assets and verify usage control.
- A `Credential Issuer` issues _verifiable credentials_ used by participant agents to allow access to datasets and verify usage control.

The diagram below depicts the relationships between `ParticipantAgent` types:

![](./m.participant.entities.png)

- A `CatalogService` is a `Participant Agent` that makes a [DCAT Catalog](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog) available to other participants.
- A `Catalog` contains one or more `Asset Entries`, which are [DCAT Datasets](https://www.w3.org/TR/vocab-dcat-3/#Class:Dataset). A `Catalog` also contains **_at least one_**
[DCAT DataService](https://www.w3.org/TR/vocab-dcat-3/#Class:Data_Service) that references a `Connector` where assets may be obtained.
- An `Asset Entry` has **one** `Offer`, which is an [ODRL Offer](https://www.w3.org/TR/odrl-model/#policy-offer) describing the _usage control policy_ associated with the asset.
- A `Connector` is a `Participant Agent` that performs `Contract Negotiation` and `Asset Transfer` operations with another connector. An outcome of a `ContractNegotiation` may
be the production of an `Agreement`, which is an [ODRL Agreement](https://www.w3.org/TR/odrl-model/#policy-agreement) defining the _usage control policy_ agreed to for an asset.
- A `Catalog` contains one or more `Datasets`, which are [DCAT Datasets](https://www.w3.org/TR/vocab-dcat-3/#Class:Dataset). A `Catalog` also contains **_at least one_**
[DCAT DataService](https://www.w3.org/TR/vocab-dcat-3/#Class:Data_Service) that references a `Connector` where datasets may be obtained.
- An `Dataset` has **one** `Offer`, which is an [ODRL Offer](https://www.w3.org/TR/odrl-model/#policy-offer) describing the _usage control policy_ associated with the dataset.
juliapampus marked this conversation as resolved.
Show resolved Hide resolved
- A `Connector` is a `Participant Agent` that performs `Contract Negotiation` and `Transfer Process` operations with another connector. An outcome of a `ContractNegotiation` may
be the production of an `Agreement`, which is an [ODRL Agreement](https://www.w3.org/TR/odrl-model/#policy-agreement) defining the _usage control policy_ agreed to for a dataset.

## 2.2 Classes

Expand All @@ -48,18 +48,18 @@ The classes and definitions used in the dataspace protocol are reused from diffe

A `Catalog` is a [DCAT Catalog](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog) with the following attributes:

- 0..N `Asset Entries`. Since a catalog may be dynamically generated for a request based on the requesting participant's credentials it is possible for it to contain 0 matching
asset entries. (DCAT PROFILE)
- 1..N [DCAT DataService](https://www.w3.org/TR/vocab-dcat-3/#Class:Data_Service) that references a `Connector` where assets may be obtained. (DCAT PROFILE)
- 0..N `Datasets`. Since a catalog may be dynamically generated for a request based on the requesting participant's credentials it is possible for it to contain 0 matching
datasets. (DCAT PROFILE)
- 1..N [DCAT DataService](https://www.w3.org/TR/vocab-dcat-3/#Class:Data_Service) that references a `Connector` where datasets may be obtained. (DCAT PROFILE)

### 2.2.2 Asset Entry
### 2.2.2 Dataset

An `Asset Entry` is a [DCAT Dataset](https://www.w3.org/TR/vocab-dcat-3/#Class:Dataset) with the following attributes:
A `Dataset` is a [DCAT Dataset](https://www.w3.org/TR/vocab-dcat-3/#Class:Dataset) with the following attributes:

- 1..N `hasPolicy` attributes that contain an ODRL `Offer` defining the usage control policy associated with the asset. **_Offers must NOT contain any target attributes. The
target of an offer is the asset associated with the containing asset entry._** (ODRL PROFILE)
- 1..N `hasPolicy` attributes that contain an ODRL `Offer` defining the usage control policy associated with the dataset. **_Offers must NOT contain any target attributes. The
juliapampus marked this conversation as resolved.
Show resolved Hide resolved
target of an offer is the associated dataset._** (ODRL PROFILE)
- 1..N [DCAT Distributions](https://www.w3.org/TR/vocab-dcat-3/#Class:Distribution). Each distribution must have at least one `DataService` which specifies where the distribution
is obtained. Specifically, a `DataService` specifies the endpoint for initiating a `ContractNegotiation` and `AssetTransfer`. (DCAT PROFILE)
is obtained. Specifically, a `DataService` specifies the endpoint for initiating a `ContractNegotiation` and `TransferProcess`. (DCAT PROFILE)

### 2.2.3 Offer

Expand All @@ -73,5 +73,5 @@ An `Offer` is an [ODRL Offer](https://www.w3.org/TR/odrl-model/#policy-offer) wi

An `Agreement` is an [ODRL Agreement](https://www.w3.org/TR/odrl-model/#policy-agreement) with the following attributes:

- The `Agreement` class must include one `target` attribute that is the UUID of the asset the agreement is associated with. An agreement is therefore associated with **EXACTLY
ONE** asset. (ODRL PROFILE)
- The `Agreement` class must include one `target` attribute that is the UUID of the dataset the agreement is associated with. An agreement is therefore associated with **EXACTLY
ONE** dataset. (ODRL PROFILE)
20 changes: 10 additions & 10 deletions model/terminology.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@ This and the following section defines the core concepts, entities, and relation

## Dataspace

A `Dataspace` is a set of technical services that facilitate interoperable asset sharing between entities.
A `Dataspace` is a set of technical services that facilitate interoperable `Dataset` sharing between entities.

## DataspaceAuthority

A `DataspaceAuthority` is an entity that manages a `Dataspace`.

## Participant

A `Participant` is a `Dataspace` member that provides and/or consumes assets.
A `Participant` is a `Dataspace` member that provides and/or consumes `Datasets`.

## ParticipantAgent

Expand All @@ -35,38 +35,38 @@ If a trusted technology system is required that records and verifies those doma

A `DataspaceRegistrationService` is a technology system that maintains the state of `Participants` in a `Dataspace`.

## Asset
## Dataset

Data or a technical service that can be shared by a `Participant`.

## Policy

A set of rules, duties, and obligations that define the terms of use for an `Asset`.
A set of rules, duties, and obligations that define the terms of use for an `Dataset`.
juliapampus marked this conversation as resolved.
Show resolved Hide resolved

## Offer

A concrete `Policy` associated with a specific `Asset`.
A concrete `Policy` associated with a specific `Dataset`.

## Agreement

A concrete `Policy` associated with a specific `Asset` that has been signed by both the provider and consumer `Participants`.
A concrete `Policy` associated with a specific `Dataset` that has been signed by both the provider and consumer `Participants`.

## Catalog

A collection of entries representing `Assets` and their `Offers` that is advertised by a provider `Participant`.
A collection of entries representing `Datasets` and their `Offers` that is advertised by a provider `Participant`.

## CatalogService

A `ParticipantAgent` that makes a `Catalog` accessible to `Participants`.

## Connector (DataService)

A `ParticipantAgent` that produces `Agreements` and manages `Asset` sharing.
A `ParticipantAgent` that produces `Agreements` and manages `Dataset` sharing.

## Contract Negotiation

A set of interactions between a provider `Connector` and consumer `Connector` that establish an `Agreement`.

## Asset Transfer
## Dataset Transfer

A set of interactions between a provider `Connector` and consumer `Connector` that give access to an `Asset` under the terms of an `Agreement`.
A set of interactions between a provider `Connector` and consumer `Connector` that give access to an `Dataset` under the terms of an `Agreement`.
juliapampus marked this conversation as resolved.
Show resolved Hide resolved
Loading