Skip to content

Commit 2b463fc

Browse files
juliapampusarnoweiss
juliapampus
and
arnoweiss
authored
refactor: improve readability of ToC and bindings (#116)
* refactor: improve readability of ToCs * chore: add suggestion from review Co-authored-by: Arno Weiß <[email protected]> --------- Co-authored-by: Arno Weiß <[email protected]>
1 parent 276fec9 commit 2b463fc

File tree

4 files changed

+111
-157
lines changed

4 files changed

+111
-157
lines changed

‎specifications/catalog/catalog.binding.https.md

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -24,11 +24,9 @@ a [Catalog Error](#error-catalog-error) in the response body.
2424
| https://provider.com/catalog/request | `POST` | [[[#catalog-request-post]]] |
2525
| https://provider.com/catalog/datasets/:id | `GET` | [[[#catalog-datasets-get]]] |
2626

27-
### The `catalog/request` Endpoint (Provider-side)
27+
### Catalog Request Endpoint {#catalog-request-post}
2828

29-
#### POST {#catalog-request-post}
30-
31-
##### Request
29+
**Request**
3230

3331
The [Catalog Request Message](#catalog-request-message) corresponds to `POST https://<base>/catalog/request`:
3432

@@ -47,7 +45,7 @@ Authorization: ...</pre>
4745
expression or query to be executed as part of the [=Catalog=] request. If a filter expression is not supported by an
4846
implementation, it must return a HTTP 400 (Bad Request) response.
4947

50-
##### Response
48+
**Response**
5149

5250
If the request is successful, the [=Catalog Service=] must return an HTTP 200 (OK) with a response body containing
5351
a [Catalog](#ack-catalog).
@@ -57,11 +55,9 @@ a [Catalog](#ack-catalog).
5755
</pre>
5856
</aside>
5957

60-
### The `catalog/datasets/:id` Endpoint (Provider-side)
61-
62-
#### GET {#catalog-datasets-get}
58+
### Dataset Request Endpoint {#catalog-datasets-get}
6359

64-
##### Request
60+
**Request**
6561

6662
The [Dataset Request Message](#dataset-request-message) corresponds
6763
to `GET https://<base>/catalog/datasets/:id}`:
@@ -76,7 +72,7 @@ Authorization: ...</pre>
7672
contents of the `Authorization` header are detailed in
7773
the [[[#authorization]]].
7874

79-
##### Response
75+
**Response**
8076

8177
If the request is successful, the [=Catalog Service=] must return an HTTP 200 (OK) with a response body containing
8278
a [Dataset](#ack-dataset).

‎specifications/common/common.protocol.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ All requests to HTTPS endpoints should use the `Authorization` header to include
66
of such tokens are not part of these specifications. The `Authorization` HTTP header is optional if the [=Connector=]
77
does not require authorization.
88

9-
## Schemas, Contexts, and Message Processing
9+
## Schemas & Contexts
1010

1111
All protocol [=Messages=] are normatively defined by a [[json-schema]]. This specification also uses JSON-LD 1.1 and provides
1212
a JSON-LD context to serialize data structures and [=Message=] types as it facilitates extensibility. The JSON-LD context is
@@ -15,7 +15,7 @@ type. This allows implementations to choose whether to process [=Messages=] as p
1515
interoperability between those approaches. Extensions that use JSON-LD are encouraged to provide similar contexts that
1616
facilitate this approach to interoperability.
1717

18-
## Exposure of Dataspace Protocol Versions
18+
## Exposure of Versions {#exposure-of-dataspace-protocol-versions}
1919

2020
### Generic Definition
2121

‎specifications/negotiation/contract.negotiation.binding.https.md

Lines changed: 56 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -41,20 +41,18 @@ authorization.
4141

4242
## Provider Path Bindings
4343

44-
| Endpoint | Method | Description |
45-
|:----------------------------------------------------------------------|:-------|:------------------------------------------------------------|
46-
| https://provider.com/negotiations/:providerPid | `GET` | [[[#negotiations-get-provider]]] |
47-
| https://provider.com/negotiations/request | `POST` | [[[#negotiations-request-post]]] |
48-
| https://provider.com/negotiations/:providerPid/request | `POST` | [[[#negotiations-providerpid-request-post]]] |
49-
| https://provider.com/negotiations/:providerPid/events | `POST` | [[[#negotiations-providerpid-events-post]]] |
50-
| https://provider.com/negotiations/:providerPid/agreement/verification | `POST` | [[[#negotiations-providerpid-agreement-verification-post]]] |
51-
| https://provider.com/negotiations/:providerPid/termination | `POST` | [[[#negotiations-providerpid-termination-post]]] |
44+
| Endpoint | Method | Path |
45+
|:------------------------------------------------------------|:-------|:----------------------------------------------------|
46+
| [[[#negotiations-get-provider]]] | `GET` | `/negotiations/:providerPid` |
47+
| [[[#negotiations-request-post]]] | `POST` | `/negotiations/request` |
48+
| [[[#negotiations-providerpid-request-post]]] | `POST` | `/negotiations/:providerPid/request` |
49+
| [[[#negotiations-providerpid-events-post]]] | `POST` | `/negotiations/:providerPid/events` |
50+
| [[[#negotiations-providerpid-agreement-verification-post]]] | `POST` | `/negotiations/:providerPid/agreement/verification` |
51+
| [[[#negotiations-providerpid-termination-post]]] | `POST` | `/negotiations/:providerPid/termination` |
5252

53-
### The `negotiations` Endpoint _(Provider-side)_
53+
### Contract Negotiation Endpoint {#negotiations-get-provider}
5454

55-
#### GET {#negotiations-get-provider}
56-
57-
##### Request
55+
**Request**
5856

5957
A CN can be accessed by a [=Consumer=] sending a GET request to `negotiations/:providerPid`:
6058

@@ -65,7 +63,7 @@ Authorization: ...</pre>
6563
</aside>
6664

6765

68-
##### Response
66+
**Response**
6967

7068
If the CN is found and the client is authorized, the [=Provider=] must return an HTTP 200 (OK) response and a body
7169
containing the [Contract Negotiation](#ack-contract-negotiation):
@@ -80,11 +78,9 @@ containing the [Contract Negotiation](#ack-contract-negotiation):
8078
Predefined states are: `REQUESTED`, `OFFERED`, `ACCEPTED`, `AGREED`, `VERIFIED`, `FINALIZED`, and `TERMINATED` (
8179
see [[[#contract-negotiation-states]]]).
8280

83-
### The `negotiations/request` Endpoint _(Provider-side)_
84-
85-
#### POST {#negotiations-request-post}
81+
### Contract Request Endpoint (init) {#negotiations-request-post}
8682

87-
##### Request
83+
**Request**
8884

8985
A CN is started and placed in the `REQUESTED` state when a [=Consumer=] POSTs an
9086
initiating [Contract Request Message](#contract-request-message)
@@ -104,7 +100,7 @@ Authorization: ...</pre>
104100
that [=Providers=] should properly handle the cases where a trailing `/` is included
105101
with or absent from the `callbackAddress` when resolving full URL.
106102

107-
##### Response
103+
**Response**
108104

109105
The [=Provider=] must return an HTTP 201 (Created) response with a body containing
110106
the [Contract Negotiation](#ack-contract-negotiation):
@@ -114,11 +110,9 @@ the [Contract Negotiation](#ack-contract-negotiation):
114110
</pre>
115111
</aside>
116112

117-
### The `negotiations/:providerPid/request` Endpoint _(Provider-side)_
113+
### Contract Request Endpoint {#negotiations-providerpid-request-post}
118114

119-
#### POST {#negotiations-providerpid-request-post}
120-
121-
##### Request
115+
**Request**
122116

123117
A [=Consumer=] may make an [=Offer=] by POSTing
124118
a [Contract Request Message](#contract-request-message)
@@ -131,16 +125,14 @@ Authorization: ...</pre>
131125
</pre>
132126
</aside>
133127

134-
##### Response
128+
**Response**
135129

136130
If the message is successfully processed, the [=Provider=] must return an HTTP 200 (OK) response. The response body is
137131
not specified and clients are not required to process it.
138132

139-
### The `negotiations/:providerPid/events` Endpoint _(Provider-side)_
140-
141-
#### POST {#negotiations-providerpid-events-post}
133+
### Contract Negotiation Event Endpoint {#negotiations-providerpid-events-post}
142134

143-
##### Request
135+
**Request**
144136

145137
A [=Consumer=] can POST
146138
a [Contract Negotiation Event Message](#contract-negotiation-event-message)
@@ -153,7 +145,7 @@ Authorization: ...</pre>
153145
</pre>
154146
</aside>
155147

156-
##### Response
148+
**Response**
157149

158150
If the CN's state is successfully transitioned, the [=Provider=] must return an HTTP code 200 (OK). The response body is
159151
not specified and clients are not required to process it.
@@ -162,11 +154,9 @@ If the current [=Offer=] was created by the [=Consumer=], the [=Provider=] must
162154
with a [Contract Negotiation Error](#error-contract-negotiation-error) in the
163155
response body.
164156

165-
### The `negotiations/:providerPid/agreement/verification` Endpoint _(Provider-side)_
157+
### Contract Agreement Verification Endpoint {#negotiations-providerpid-agreement-verification-post}
166158

167-
#### POST {#negotiations-providerpid-agreement-verification-post}
168-
169-
##### Request
159+
**Request**
170160

171161
The [=Consumer=] can POST
172162
a [Contract Agreement Verification Message](#contract-agreement-verification-message)
@@ -179,16 +169,14 @@ Authorization: ...</pre>
179169
</pre>
180170
</aside>
181171

182-
##### Response
172+
**Response**
183173

184174
If the CN's state is successfully transitioned, the [=Provider=] must return an HTTP code 200 (OK). The response body is
185175
not specified and clients are not required to process it.
186176

187-
### The `negotiations/:providerPid/termination` Endpoint _(Provider-side)_
188-
189-
#### POST {#negotiations-providerpid-termination-post}
177+
### Contract Negotiation Termination Endpoint {#negotiations-providerpid-termination-post}
190178

191-
##### Request
179+
**Request**
192180

193181
The [=Consumer=] can POST
194182
a [Contract Negotiation Termination Message](#contract-negotiation-termination-message)
@@ -201,36 +189,34 @@ Authorization: ...</pre>
201189
</pre>
202190
</aside>
203191

204-
##### Response
192+
**Response**
205193

206194
If the CN's state is successfully transitioned, the [=Provider=] must return HTTP code 200 (OK). The response body is
207195
not specified and clients are not required to process it.
208196

209-
## Consumer Callback Path Bindings
210-
211-
| Endpoint | Method | Description |
212-
|:---------------------------------------------------------------------|:-------|:-------------------------------------------------|
213-
| https://consumer.com/negotiations/offers | `POST` | [[[#negotiations-offers-post]]] |
214-
| https://consumer.com/:callback/negotiations/:consumerPid | `GET` | [[[#negotiations-get-consumer]]] |
215-
| https://consumer.com/:callback/negotiations/:consumerPid/offers | `POST` | [[[#negotiations-consumerpid-offers-post]]] |
216-
| https://consumer.com/:callback/negotiations/:consumerPid/agreement | `POST` | [[[#negotiations-consumerpid-agreement-post]]] |
217-
| https://consumer.com/:callback/negotiations/:consumerPid/events | `POST` | [[[#negotiations-consumerpid-events-post]]] |
218-
| https://consumer.com/:callback/negotiations/:consumerPid/termination | `POST` | [[[#negotiations-consumerpid-termination-post]]] |
197+
## Consumer Path Bindings
219198

220-
**_Note:_** The `:callback` can be chosen freely by the implementations.
199+
| Endpoint | Method | Path |
200+
|:-------------------------------------------------|:-------|:---------------------------------------------------|
201+
| [[[#negotiations-get-consumer]]] | `GET` | `/:callback/negotiations/:consumerPid` |
202+
| [[[#negotiations-offers-post]]] | `POST` | `/negotiations/offers` |
203+
| [[[#negotiations-consumerpid-offers-post]]] | `POST` | `/:callback/negotiations/:consumerPid/offers` |
204+
| [[[#negotiations-consumerpid-agreement-post]]] | `POST` | `/:callback/negotiations/:consumerPid/agreement` |
205+
| [[[#negotiations-consumerpid-events-post]]] | `POST` | `/:callback/negotiations/:consumerPid/events` |
206+
| [[[#negotiations-consumerpid-termination-post]]] | `POST` | `/:callback/negotiations/:consumerPid/termination` |
221207

222208
### Prerequisites
223209

224210
All callback paths are relative to the `callbackAddress` base URL specified in
225211
the [Contract Request Message](#contract-request-message) that initiated a CN. For example, if the `callbackAddress` is
226-
specified as `https://consumer.com/callback` and a callback path binding is `negotiations/:consumerPid/offers`, the
227-
resolved URL will be `https://consumer.com/callback/negotiations/:consumerPid/offers`.
212+
specified as `https://consumer.com/:callback` and a callback path binding is `negotiations/:consumerPid/offers`, the
213+
resolved URL will be `https://consumer.com/:callback/negotiations/:consumerPid/offers`.
228214

229-
### The `negotiations` Endpoint _(Consumer-side)_
215+
**_Note:_** The `:callback` can be chosen freely by the implementations.
230216

231-
#### GET {#negotiations-get-consumer}
217+
### Contract Negotiation Endpoint {#negotiations-get-consumer}
232218

233-
##### Request
219+
**Request**
234220

235221
A CN can be accessed by a [=Provider=] sending a GET request to the `negotiations/:consumerPid` callback:
236222

@@ -241,7 +227,7 @@ Authorization: ...</pre>
241227
</aside>
242228

243229

244-
##### Response
230+
**Response**
245231

246232
If the CN is found and the client is authorized, the [=Consumer=] must return an HTTP 200 (OK) response and a body
247233
containing the [Contract Negotiation](#ack-contract-negotiation):
@@ -256,11 +242,9 @@ containing the [Contract Negotiation](#ack-contract-negotiation):
256242
Predefined states are: `REQUESTED`, `OFFERED`, `ACCEPTED`, `AGREED`, `VERIFIED`, `FINALIZED`, and `TERMINATED` (
257243
see [[[#contract-negotiation-states]]]).
258244

259-
### The `negotiations/offers` Endpoint _(Consumer-side)_
245+
### Contract Offer Endpoint (init) {#negotiations-offers-post}
260246

261-
#### POST {#negotiations-offers-post}
262-
263-
##### Request
247+
**Request**
264248

265249
A CN is started and placed in the `OFFERED` state when a [=Provider=] POSTs
266250
a [Contract Offer Message](#contract-offer-message) to `negotiations/offers`:
@@ -279,7 +263,7 @@ Authorization: ...</pre>
279263
should properly handle the cases where a trailing / is included with or absent from the `callbackAddress` when
280264
resolving full URL.
281265

282-
##### Response
266+
**Response**
283267

284268
The [=Consumer=] must return an HTTP 201 (Created) response with a body containing
285269
the [Contract Negotiation](#ack-contract-negotiation):
@@ -289,11 +273,9 @@ the [Contract Negotiation](#ack-contract-negotiation):
289273
</pre>
290274
</aside>
291275

292-
### The `negotiations/:consumerPid/offers` Endpoint _(Consumer-side)_
293-
294-
#### POST {#negotiations-consumerpid-offers-post}
276+
### Contract Offer Endpoint {#negotiations-consumerpid-offers-post}
295277

296-
##### Request
278+
**Request**
297279

298280
A [=Provider=] may make an [=Offer=] by POSTing a [Contract Offer Message](#contract-offer-message) to
299281
the `negotiations/:consumerPid/offers` callback:
@@ -305,16 +287,14 @@ Authorization: ...</pre>
305287
</pre>
306288
</aside>
307289

308-
##### Response
290+
**Response**
309291

310292
If the message is successfully processed, the [=Consumer=] must return an HTTP 200 (OK) response. The response body is
311293
not specified and clients are not required to process it.
312294

313-
### The `negotiations/:consumerPid/agreement` Endpoint _(Consumer-side)_
295+
### Contract Agreement Endpoint {#negotiations-consumerpid-agreement-post}
314296

315-
#### POST {#negotiations-consumerpid-agreement-post}
316-
317-
##### Request
297+
**Request**
318298

319299
The [=Provider=] can POST a [Contract Agreement Message](#contract-agreement-message) to
320300
the `negotiations/:consumerPid/agreement` callback to create an [=Agreement=].
@@ -326,16 +306,14 @@ Authorization: ...</pre>
326306
</pre>
327307
</aside>
328308

329-
##### Response
309+
**Response**
330310

331311
If the CN's state is successfully transitioned, the [=Consumer=] must return an HTTP code 200 (OK). The response body is
332312
not specified and clients are not required to process it.
333313

334-
### The `negotiations/:consumerPid/events` Endpoint _(Consumer-side)_
335-
336-
#### POST {#negotiations-consumerpid-events-post}
314+
### Contract Negotiation Event Endpoint {#negotiations-consumerpid-events-post}
337315

338-
##### Request
316+
**Request**
339317

340318
A [=Provider=] can POST a [Contract Negotiation Event Message](#contract-negotiation-event-message) to
341319
the `negotiations/:consumerPid/events` callback with an `eventType` of `FINALIZED` to finalize an [=Agreement=].
@@ -347,16 +325,14 @@ Authorization: ...</pre>
347325
</pre>
348326
</aside>
349327

350-
##### Response
328+
**Response**
351329

352330
If the CN's state is successfully transitioned, the [=Consumer=] must return HTTP code 200 (OK). The response body is
353331
not specified and clients are not required to process it.
354332

355-
### The `negotiations/:consumerPid/termination` Endpoint _(Consumer-side)_
356-
357-
#### POST {#negotiations-consumerpid-termination-post}
333+
### Contract Negotiation Termination Endpoint {#negotiations-consumerpid-termination-post}
358334

359-
##### Request
335+
**Request**
360336

361337
The [=Provider=] can POST a [Contract Negotiation Termination Message](#contract-negotiation-termination-message) to
362338
terminate a CN.
@@ -368,7 +344,7 @@ Authorization: ...</pre>
368344
</pre>
369345
</aside>
370346

371-
##### Response
347+
**Response**
372348

373349
If the CN's state is successfully transitioned, the [=Consumer=] must return HTTP code 200 (OK). The response body is
374350
not specified and clients are not required to process it.

0 commit comments

Comments
 (0)