feat: replace message diagrams with autogenerated tables (#111)

Author: arnoweiss

.github/workflows/autopublish.yaml

@@ -13,17 +13,17 @@ jobs:
       contents: write
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22.x
+      - uses: ./.github/actions/setup-java
+      - name: build java
+        run: |
+          cd artifacts
+          ./gradlew build
+          ./gradlew generateTablesFromSchemas
+          cd ..
       - name: Copy files for correct web access
         run: |
           chmod +x ./.github/workflows/script.sh
           ./.github/workflows/script.sh
-      - name: Run Respec
-        run:
-          sudo npx puppeteer browsers install chrome
-          npx respec --src index.html --out index.html.build.html -t 60 --disable-sandbox --verbose
       - uses: actions/upload-pages-artifact@v3
         with:
           path: .

.github/workflows/script.sh

@@ -1,15 +1,18 @@
 #!/bin/bash
+set -e
+
+mkdir ./figures
 mkdir -p ./message/schema
 mkdir -p ./message/example
-mkdir -p ./message/diagram
-mkdir ./figures
+mkdir -p ./message/table
 cp ./artifacts/src/main/resources/**/* ./message/schema || true
 echo "successfully copied message schemas"
-cp -R "./artifacts/src/main/resources"/**/"example"/* ./message/example
+cp -r "./artifacts/src/main/resources"/**/"example"/* ./message/example
 echo "successfully copied message examples"
-cp -R "./specifications"/**/"message/diagram"/*".png" message/diagram
-echo "successfully copied message diagrams"
-cp -R "./specifications"/**/"figures"/*".png" ./figures/
+cp -r "./specifications"/**/"figures"/*".png" ./figures/
 echo "successfully copied figures"
+cp -r "./artifacts/build/generated/tables"/*".html" ./message/table
+echo "successfully copied message property tables"
+
 #rm -rf artifacts
 #echo "successfully removed artifacts"

specifications/catalog/catalog.binding.https.md

@@ -79,7 +79,7 @@ Authorization: ...</pre>
 ##### Response
 
 If the request is successful, the [=Catalog Service=] must return an HTTP 200 (OK) with a response body containing
-a [Dataset](#ack-dataset) (which isa [DCAT Dataset](https://www.w3.org/TR/vocab-dcat-3/#Class:Dataset) type described by the [=Catalog Protocol=]).
+a [Dataset](#ack-dataset).
 
 <aside class="example" title="Dataset Response">
     <pre class="json" data-include="message/example/dataset.json">

specifications/catalog/catalog.protocol.md

@@ -15,14 +15,14 @@ Servers have no obligation to process properties that are not part of the schema
 
 ### Catalog Request Message
 
-|                     |                                                                              |
-|---------------------|------------------------------------------------------------------------------|
-| **Sent by**         | [=Consumer=]                                                                 |
-| **Resulting state** | `TERMINATED`                                                                 |
-| **Response**        | [ACK](#ack-catalog) or [ERROR](#error-catalog-error)                         |
-| **Schema**          | [JSON Schema](message/schema/catalog-request-message-schema.json)          |
-| **Example**         | [Message](message/example/catalog-request-message.json)                    |
-| **Diagram(s)**      | ![](message/diagram/catalog-request-message.png "Catalog Request Message") |
+|                     |                                                                                             |
+|---------------------|---------------------------------------------------------------------------------------------|
+| **Sent by**         | [=Consumer=]                                                                                |
+| **Resulting state** | `TERMINATED`                                                                                |
+| **Response**        | [ACK](#ack-catalog) or [ERROR](#error-catalog-error)                                        |
+| **Schema**          | [JSON Schema](message/schema/catalog-request-message-schema.json)                           |
+| **Example**         | [Message](message/example/catalog-request-message.json)                                     |
+| **Properties**      | <p data-include="message/table/catalogrequestmessage.html" data-include-format="html"></p> |
 
 The Catalog Request Message is message sent by a [=Consumer=] to
 a [=Catalog Service=].
@@ -37,14 +37,14 @@ The [=Catalog Service=] must respond with a [Catalog](#ack-catalog) that adheres
 
 ### Dataset Request Message
 
-|                     |                                                                     |
-|---------------------|---------------------------------------------------------------------|
-| **Sent by**         | [=Consumer=]                                                        |
-| **Resulting state** | `TERMINATED`                                                        |
-| **Response**        | [ACK](#ack-catalog) or [ERROR](#error-catalog-error)                |
-| **Schema**          | [JSON Schema](message/schema/dataset-request-message-schema.json) |
-| **Example**         | [Message](message/example/dataset-request-message.json)           |
-| **Diagram(s)**      | ![](message/diagram/dataset-request-message.png)                  |
+|                     |                                                                                             |
+|---------------------|---------------------------------------------------------------------------------------------|
+| **Sent by**         | [=Consumer=]                                                                                |
+| **Resulting state** | `TERMINATED`                                                                                |
+| **Response**        | [ACK](#ack-catalog) or [ERROR](#error-catalog-error)                                        |
+| **Schema**          | [JSON Schema](message/schema/dataset-request-message-schema.json)                           |
+| **Example**         | [Message](message/example/dataset-request-message.json)                                     |
+| **Properties**      | <p data-include="message/table/datasetrequestmessage.html" data-include-format="html"></p> |
 
 The Dataset Request Message is message sent by a [=Consumer=] to
 a [=Catalog Service=].
@@ -62,42 +62,37 @@ provided in protocol-dependent forms, e.g., for an HTTPS binding in the request
 
 ### ACK - Catalog
 
-|                |                                                     |
-|----------------|-----------------------------------------------------|
-| **Sent by**    | [=Provider=]                                        |
-| **Schema**     | [JSON Schema](message/schema/catalog-schema.json) |
-| **Example**    | [Catalog Example](message/example/catalog.json)   |
-| **Diagram(s)** | ![](message/diagram/catalog.png)                  |
+|                |                                                                               |
+|----------------|-------------------------------------------------------------------------------|
+| **Sent by**    | [=Provider=]                                                                  |
+| **Schema**     | [JSON Schema](message/schema/catalog-schema.json)                             |
+| **Example**    | [Catalog Example](message/example/catalog.json)                               |
+| **Properties**      | <p data-include="message/table/catalog.html" data-include-format="html"></p> |
 
 The [=Catalog=] contains all [Datasets](#dataset) which the requester shall see.
 
 ### ACK - Dataset
 
-|                |                                                     |
-|----------------|-----------------------------------------------------|
-| **Sent by**    | [=Provider=]                                        |
-| **Schema**     | [JSON Schema](message/schema/dataset-schema.json) |
-| **Example**    | [Dataset Example](message/example/dataset.json)   |
-| **Diagram(s)** | ![](message/diagram/dataset.png)                  |
+|                |                                                                               |
+|----------------|-------------------------------------------------------------------------------|
+| **Sent by**    | [=Provider=]                                                                  |
+| **Schema**     | [JSON Schema](message/schema/dataset-schema.json)                             |
+| **Example**    | [Dataset Example](message/example/dataset.json)                               |
+| **Properties**      | <p data-include="message/table/dataset.html" data-include-format="html"></p> |
 
 ### ERROR - Catalog Error
 
-|                |                                                           |
-|----------------|-----------------------------------------------------------|
-| **Sent by**    | [=Consumer=], [=Provider=]                                |
-| **Schema**     | [JSON Schema](message/schema/catalog-error-schema.json) |
-| **Example**    | [Error](message/example/catalog-error.json)             |
-| **Diagram(s)** | ![](message/diagram/catalog-error.png)                  |
+|                |                                                                                    |
+|----------------|------------------------------------------------------------------------------------|
+| **Sent by**    | [=Consumer=], [=Provider=]                                                         |
+| **Schema**     | [JSON Schema](message/schema/catalog-error-schema.json)                            |
+| **Example**    | [Error](message/example/catalog-error.json)                                        |
+| **Properties**      | <p data-include="message/table/catalogerror.html" data-include-format="html"></p> |
 
 A Catalog Error is used when an error occurred after a [Catalog Request Message](#catalog-request-message) or
 a [Dataset Request Message](#dataset-request-message) and the [=Provider=] cannot
 provide its [=Catalog=] to the requester.
 
-| Field     | Type          | Description                                                 |
-|-----------|---------------|-------------------------------------------------------------|
-| `code`    | String        | An optional implementation-specific error code.             |
-| `reasons` | Array[object] | An optional array of implementation-specific error objects. |
-
 ## Technical Considerations
 
 ### Queries and Filter Expressions