Merge pull request #46 from arnoweiss/main

chore: edits on model, common, catalog sections' links

.github/workflows/autopublish.yaml

@@ -16,10 +16,18 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22.x
-      - name: Inject md to html
+      - name: Copy files for correct web access
         run: |
-          chmod +x ./scripts/replace.sh
-          ./scripts/replace.sh
+          mkdir ./message/diagram -p
+          mkdir ./message/schema
+          mkdir ./message/shape
+          mkdir ./figures
+          cp ./**/message/diagram/*.png ./message/diagram/
+          cp ./**/message/schema/*.json ./message/schema/
+          cp ./**/message/shape/*.ttl ./message/shape/
+          cp ./model/*.png .
+          cp ./**/figures/*.png ./figures/
+          cp ./releases/* . -r
       - name: Run Respec
         run:
           sudo npx puppeteer browsers install chrome

.gitignore

@@ -7,6 +7,8 @@
 *.zip
 *.tar.gz
 *.rar
+# only top level images
+*.png
 
 .idea
 *.iml
@@ -19,7 +21,7 @@
 .DS_Store
 .env
 
-index.html
 /message
 /2024-1
-/v0.8
+/v0.8
+/figures

README.md

@@ -64,7 +64,7 @@ A [Connector](./model/terminology.md#connector--data-service-) will implement ad
 
 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).
 
-![Overview on protocol and context](./resources/figures/ProtocolOverview.png)
+![Overview on protocol and context](./resources/figures/ProtocolOverview.png "Overview on protocol and context")
 
 ## Best Practices
 
@@ -77,3 +77,4 @@ Users of this specification are invited to provide feedback such as, but not lim
 * What did you like in this document?
 
 Please provide your feedback as Issue in our [GitHub repository](https://github.com/International-Data-Spaces-Association/ids-specification/issues).
+

WEBSITE.md

@@ -0,0 +1,30 @@
+## Static Rendering and Web Deployment
+
+This repository contains the set of artifacts that make up the normative
+and non-normative sections of the Dataspace Protocol. All artifacts are
+bundled by the [respec framework](https://www.respec.org) which takes care
+of rendering a static website. 
+
+### Conventions
+
+The following extensions to the basic markdown syntax are used in this 
+specification project. Keep them handy and navigating the document will 
+be easy.
+
+- Referencing an external specification document. [Respec Docs](https://respec.org/docs/#references-0)
+    - with identifier inline `[[foreign-spec-id]]`
+    - with the foreign spec's display name inline `[[[foreign-spec-id]]]`
+    - 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).
+- Defining terminology: A term is defined by wrapping it in `<dfn>Defineable</dfn>`. [Respec Docs](https://respec.org/docs/#definitions-and-linking)
+- 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)
+- 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`.
+    - with the sections number and display name inline `[[[#my-section-id]]]`
+    - If that's not desired, ordinary links work as well. `[my custom link](#my-section-id)`
+    - referencing terminology: `[=Defineable=]`. This will work out of the box with Plurals such that `[=Definables=]` refers to the definition of `<dfn>Defineable</dfn>`.
+- Code blocks work natively like in markdown.
+
+### Rendering in your IDE
+
+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.
+2. Open the `index.html` file.
+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.

catalog/catalog.binding.https.md

@@ -1,44 +1,36 @@
 # Catalog HTTPS Binding
 
-This specification defines a RESTful API over HTTPS for the [Catalog Protocol](./catalog.protocol.md).
+This specification defines a RESTful API over HTTPS for the [Catalog Protocol](#catalog-protocol).
 
-* [1 Introduction](#1-introduction)
-  * [1.1 Prerequisites](#11-prerequisites)
-  * [1.2 Catalog Error](#12-catalog-error)
-* [2 Path Bindings](#2-path-bindings)
-  * [2.1 The `catalog/request` Endpoint (Provider-side)](#21-the-catalogrequest-endpoint--provider-side-)
-  * [2.2 The `catalog/datasets/:id` Endpoint (Provider-side)](#22-the-catalogdatasetsid-endpoint--provider-side-)
-* [3 Technical Considerations](#3-technical-considerations)
-  * [3.1 Pagination](#31-pagination)
-  * [3.2 Compression](#32-compression)
-* [4 The Well-Known Proof Metadata Endpoint](#4-the-well-known-proof-metadata-endpoint)
+## Introduction
 
-## 1 Introduction
+### Prerequisites
 
-### 1.1 Prerequisites
-
-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`.
+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` will map
+   to `https//api.example.com/catalog/request`.
 
 2. All request and response messages must use the `application/json` media type.
 
-### 1.2 Catalog Error
+### Catalog Error
 
-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.
+In the event of a request error, the [=Catalog Service=] must return an appropriate HTTP code and
+a [Catalog Error](#error-catalog-error) in the response body.
 
-## 2 Path Bindings
+## Path Bindings
 
-| Endpoint                                  | Method | Description                |
-|:------------------------------------------|:-------|:---------------------------|
-| https://provider.com/catalog/request      | `POST` | Section [2.1.1](#211-post) |
-| https://provider.com/catalog/datasets/:id | `GET`  | Section [2.2.1](#221-get)  |
+| Endpoint                                  | Method | Description                 |
+|:------------------------------------------|:-------|:----------------------------|
+| https://provider.com/catalog/request      | `POST` | [[[#catalog-request-post]]] |
+| https://provider.com/catalog/datasets/:id | `GET`  | [[[#catalog-datasets-get]]] |
 
-### 2.1 The `catalog/request` Endpoint (Provider-side)
+### The `catalog/request` Endpoint (Provider-side)
 
-#### 2.1.1 POST
+#### POST {#catalog-request-post}
 
 ##### Request
 
-The [Catalog Request Message](./catalog.protocol.md#21-catalog-request-message) corresponds to `POST https://<base>/catalog/request`:
+The [Catalog Request Message](#catalog-request-message) corresponds to `POST https://<base>/catalog/request`:
 
 ```http request
 POST https://provider.com/catalog/request
@@ -52,21 +44,29 @@ Authorization: ...
 }
 ```
 
-- 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).
+- 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 [Authorization section](../common/common.binding.https.md#2-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](../model/terminology.md#catalog) request. If a filter expression is not supported by an implementation, it must return a HTTP 400 (Bad Request) response.
+- 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=] request. If a filter expression is not supported by an
+  implementation, it must return a HTTP 400 (Bad Request) response.
 
 ##### Response
 
-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)).
+If the request is successful, the [=Catalog Service=] must return an HTTP 200 (OK) with a response body containing
+a [Catalog](#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)).
 
-### 2.2 The `catalog/datasets/:id` Endpoint (Provider-side)
+### The `catalog/datasets/:id` Endpoint (Provider-side)
 
-#### 2.2.1 GET
+#### GET {#catalog-datasets-get}
 
 ##### Request
 
-The [Dataset Request Message](./catalog.protocol.md#22-dataset-request-message) corresponds to `GET https://<base>/catalog/datasets/:id}`:
+The [Dataset Request Message](#dataset-request-message) corresponds
+to `GET https://<base>/catalog/datasets/:id}`:
 
 ```http request
 GET https://provider.com/catalog/datasets/{id}
@@ -80,18 +80,26 @@ Authorization: ...
 }
 ```
 
-- 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).
+- 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 [[[#authorization]]].
 
 ##### Response
 
-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)).
+If the request is successful, the [=Catalog Service=] must return an HTTP 200 (OK) with a response body containing
+a [Dataset](#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)).
 
-## 3 Technical Considerations
+## Technical Considerations
 
-### 3.1 Pagination
+### Pagination
 
-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. 
-Note that the content and structure of the link query parameters is not defined by the current specification. 
+A [=Catalog Service=] may paginate the results of a [Catalog Request Message](#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.
+Note that the content and structure of the link query parameters is not defined by the current specification.
 
 The following request sequence demonstrates pagination:
 
@@ -128,19 +136,26 @@ Link: <https://provider.com/catalog?continuationToken=bn9556075bn44de8ab4bfc9014
 }
 ```
 
-### 3.2 Compression
-
-[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).
+### Compression
 
+[=Catalog Services=] MAY compress responses to
+a [Catalog Request](#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).
 
-## 4 The Well-Known Proof Metadata Endpoint
+## The Well-Known Proof Metadata Endpoint
 
-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:
+When an implementation supports protected [=Datasets=], 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 [[rfc8615]] 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](../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.
+Note that if multiple [=Connectors=] 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.