You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+2-1Lines changed: 2 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -64,7 +64,7 @@ A [Connector](./model/terminology.md#connector--data-service-) will implement ad
64
64
65
65
The same applies for the actual data that is transferred between the systems. While this document does not define the transport protocol, the structure, syntax or 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).
66
66
67
-
67
+
![Overview on protocol and context](./resources/figures/ProtocolOverview.png"Overview on protocol and context")
68
68
69
69
## Best Practices
70
70
@@ -77,3 +77,4 @@ Users of this specification are invited to provide feedback such as, but not lim
77
77
* What did you like in this document?
78
78
79
79
Please provide your feedback as Issue in our [GitHub repository](https://github.com/International-Data-Spaces-Association/ids-specification/issues).
This repository contains the set of artifacts that make up the normative
4
+
and non-normative sections of the Dataspace Protocol. All artifacts are
5
+
bundled by the [respec framework](https://www.respec.org) which takes care
6
+
of rendering a static website.
7
+
8
+
### Conventions
9
+
10
+
The following extensions to the basic markdown syntax are used in this
11
+
specification project. Keep them handy and navigating the document will
12
+
be easy.
13
+
14
+
- Referencing an external specification document. [Respec Docs](https://respec.org/docs/#references-0)
15
+
- with identifier inline `[[foreign-spec-id]]`
16
+
- with the foreign spec's display name inline `[[[foreign-spec-id]]]`
17
+
- referencing a particular section in a remote document works via ordinary markdown links. The reference has to be added to the `References` section manually (if it's not already there).
18
+
- Defining terminology: A term is defined by wrapping it in `<dfn>Defineable</dfn>`. [Respec Docs](https://respec.org/docs/#definitions-and-linking)
19
+
- Custom section IDs: If various sections have the same heading, they must be given a unique id manually via `{#my-custom-section-id}` that can then be used for referencing it. [Respec Docs](https://respec.org/docs/#example-specifying-a-custom-id-for-a-heading)
20
+
- Referencing within the document. Please note that despite separation in multiple markdown files, there is only one html document. References to sections must be flat `(#section)` instead of path-based `../catalog/catalog.protocol.md#response-types`.
21
+
- with the sections number and display name inline `[[[#my-section-id]]]`
22
+
- If that's not desired, ordinary links work as well. `[my custom link](#my-section-id)`
23
+
- referencing terminology: `[=Defineable=]`. This will work out of the box with Plurals such that `[=Definables=]` refers to the definition of `<dfn>Defineable</dfn>`.
24
+
- Code blocks work natively like in markdown.
25
+
26
+
### Rendering in your IDE
27
+
28
+
1. Locally execute the commands from the [autopublish](.github/workflows/autopublish.yaml) workflow's "Copy files for correct web access" step. All resulting folders and files are duplicates, gitignored and don't break anything.
29
+
2. Open the `index.html` file.
30
+
3. You IDE should have a feature to display html documents (either in your browser of choice or inline). Use that and you should always see the updated webpage when saving.
*[4 The Well-Known Proof Metadata Endpoint](#4-the-well-known-proof-metadata-endpoint)
5
+
## Introduction
15
6
16
-
##1 Introduction
7
+
### Prerequisites
17
8
18
-
### 1.1 Prerequisites
19
-
20
-
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`.
9
+
1. The `<base>` notation indicates the base URL for a [=Catalog Service=] endpoint. For example, if the base [=Catalog=]
10
+
URL is `api.example.com`, the URL `https://<base>/catalog/request` will map
11
+
to `https//api.example.com/catalog/request`.
21
12
22
13
2. All request and response messages must use the `application/json` media type.
23
14
24
-
### 1.2 Catalog Error
15
+
### Catalog Error
25
16
26
-
In the event of a request error, the [Catalog Service](../model/terminology.md#catalog-service) must return an appropriate HTTP code and a [Catalog Error](./catalog.protocol.md#33-error---catalog-error) in the response body.
17
+
In the event of a request error, the [=Catalog Service=] must return an appropriate HTTP code and
18
+
a [Catalog Error](#error-catalog-error) in the response body.
### 2.1 The `catalog/request` Endpoint (Provider-side)
27
+
### The `catalog/request` Endpoint (Provider-side)
36
28
37
-
#### 2.1.1 POST
29
+
#### POST {#catalog-request-post}
38
30
39
31
##### Request
40
32
41
-
The [Catalog Request Message](./catalog.protocol.md#21-catalog-request-message) corresponds to `POST https://<base>/catalog/request`:
33
+
The [Catalog Request Message](#catalog-request-message) corresponds to `POST https://<base>/catalog/request`:
42
34
43
35
```http request
44
36
POST https://provider.com/catalog/request
@@ -52,21 +44,29 @@ Authorization: ...
52
44
}
53
45
```
54
46
55
-
- 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](../common/common.binding.https.md#2-authorization).
47
+
- The `Authorization` header is optional if the [=Catalog Service=] does not require authorization. If present, the
48
+
contents of the `Authorization` header are detailed in
49
+
the [Authorization section](../common/common.binding.https.md#2-authorization).
56
50
57
-
- 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. If a filter expression is not supported by an implementation, it must return a HTTP 400 (Bad Request) response.
51
+
- The `filter` property is optional. If present, the `filter` property can contain an implementation-specific filter
52
+
expression or query to be executed as part of the [=Catalog=] request. If a filter expression is not supported by an
53
+
implementation, it must return a HTTP 400 (Bad Request) response.
58
54
59
55
##### Response
60
56
61
-
If the request is successful, the [Catalog Service](../model/terminology.md#catalog-service) must return an HTTP 200 (OK) with a response body containing a [Catalog](./catalog.protocol.md#31-ack---catalog) (which is a profiled [DCAT Catalog](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog) type described by the [Catalog Protocol](catalog.protocol.md)).
57
+
If the request is successful, the [=Catalog Service=] must return an HTTP 200 (OK) with a response body containing
58
+
a [Catalog](#ack-catalog) (which is a
59
+
profiled [DCAT Catalog](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog) type described by
60
+
the [Catalog Protocol](#catalog-protocol)).
62
61
63
-
### 2.2 The `catalog/datasets/:id` Endpoint (Provider-side)
62
+
### The `catalog/datasets/:id` Endpoint (Provider-side)
64
63
65
-
#### 2.2.1 GET
64
+
#### GET {#catalog-datasets-get}
66
65
67
66
##### Request
68
67
69
-
The [Dataset Request Message](./catalog.protocol.md#22-dataset-request-message) corresponds to `GET https://<base>/catalog/datasets/:id}`:
68
+
The [Dataset Request Message](#dataset-request-message) corresponds
69
+
to `GET https://<base>/catalog/datasets/:id}`:
70
70
71
71
```http request
72
72
GET https://provider.com/catalog/datasets/{id}
@@ -80,18 +80,26 @@ Authorization: ...
80
80
}
81
81
```
82
82
83
-
- 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](../common/common.binding.https.md#2-authorization).
83
+
- The `Authorization` header is optional if the [=Catalog Service=] does not require authorization. If present, the
84
+
contents of the `Authorization` header are detailed in
85
+
the [[[#authorization]]].
84
86
85
87
##### Response
86
88
87
-
If the request is successful, the [Catalog Service](../model/terminology.md#catalog-service) must return an HTTP 200 (OK) with a response body containing a [Dataset](./catalog.protocol.md#32-ack---dataset) (which is a [DCAT Dataset](https://www.w3.org/TR/vocab-dcat-3/#Class:Dataset) type described by the [Catalog Protocol](catalog.protocol.md)).
89
+
If the request is successful, the [=Catalog Service=] must return an HTTP 200 (OK) with a response body containing
90
+
a [Dataset](#ack-dataset) (which is
91
+
a [DCAT Dataset](https://www.w3.org/TR/vocab-dcat-3/#Class:Dataset) type described by
92
+
the [Catalog Protocol](#catalog-protocol)).
88
93
89
-
## 3 Technical Considerations
94
+
## Technical Considerations
90
95
91
-
### 3.1 Pagination
96
+
### Pagination
92
97
93
-
A [Catalog Service](../model/terminology.md#catalog-service) may paginate the results of a [Catalog Request Message](./catalog.protocol.md#21-catalog-request-message). Pagination data must be 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. Only the `next` and `previous` link relation types must be supported.
94
-
Note that the content and structure of the link query parameters is not defined by the current specification.
98
+
A [=Catalog Service=] may paginate the results of a [Catalog Request Message](#catalog-request-message). Pagination data
99
+
must be specified using [Web Linking](https://datatracker.ietf.org/doc/html/rfc5988) and the HTTP `Link` header.
100
+
The `Link` header will contain URLs for navigating to previous and subsequent results. Only the `next` and `previous`
101
+
link relation types must be supported.
102
+
Note that the content and structure of the link query parameters is not defined by the current specification.
95
103
96
104
The following request sequence demonstrates pagination:
[Catalog Services](../model/terminology.md#catalog-service) MAY compress responses to a [Catalog Request](./catalog.protocol.md#21-catalog-request-message) 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).
139
+
### Compression
134
140
141
+
[=Catalog Services=] MAY compress responses to
142
+
a [Catalog Request](#catalog-request-message) by setting the `Content-Encoding` header to `gzip` as described in
143
+
the [HTTP 1.1 Specification](https://www.rfc-editor.org/rfc/rfc9110.html#name-gzip-coding).
135
144
136
-
## 4 The Well-Known Proof Metadata Endpoint
145
+
## The Well-Known Proof Metadata Endpoint
137
146
138
-
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:
147
+
When an implementation supports protected [=Datasets=], it may offer a proof metadata
148
+
endpoint clients can use to determine proof requirements. If the implementation offers a proof data endpoint, it must
149
+
use the `dspace-trust` Well-Known Uniform Resource Identifier [[rfc8615]] at the top
150
+
of the path hierarchy:
139
151
140
152
```
141
153
/.well-known/dspace-trust
142
154
```
143
155
144
156
The contents of the response is a JSON object defined by individual trust specifications and not defined here.
145
157
146
-
Note that if multiple [Connectors](../model/terminology.md#connector--data-service-) are hosted under the same base URL, an arbitrary path segment appended to the base well-known URL can be used, for example, `https://example.com/.well-known/dspace-trust/connector1.` In this case, the document retrievable at the `dspace-trust` path segment must contain all the child paths.
158
+
Note that if multiple [=Connectors=] are hosted under the same base URL,
159
+
an arbitrary path segment appended to the base well-known URL can be used, for
160
+
example, `https://example.com/.well-known/dspace-trust/connector1.` In this case, the document retrievable at
161
+
the `dspace-trust` path segment must contain all the child paths.
0 commit comments