Merge branch 'main' into 232-circular-dependency-in-definitions

ssteinbuss · web-flow · commit abcecd867b32 · 2025-11-11T16:55:20.000+01:00
diff --git a/artifacts/buildSrc/src/main/java/org/eclipse/dsp/generation/transformer/HtmlTableTransformer.java b/artifacts/buildSrc/src/main/java/org/eclipse/dsp/generation/transformer/HtmlTableTransformer.java
@@ -54,7 +54,7 @@ private void transformProperties(Set<SchemaPropertyReference> references, boolea
     private void transformProperty(SchemaPropertyReference propertyReference, boolean required, StringBuilder builder) {
         builder.append("<tr>");
         builder.append(format("<td class=\"code\">%s</td>", propertyReference.getName()));
-        builder.append("<td>").append(required ? "required" : "optional").append("</td>");
+        builder.append("<td>").append(required ? "REQUIRED" : "OPTIONAL").append("</td>");
         var resolvedProperty = propertyReference.getResolvedProperty();
         if (resolvedProperty != null) {
             String resolvedTypes = "";
diff --git a/index.html b/index.html
@@ -65,6 +65,8 @@
 <body>
 <p class="copyright">
     This document is licensed under <a href="https://www.apache.org/licenses/LICENSE-2.0.html">The Apache License, Version 2.0</a>.
+    <br/>
+    Copyright © 2025 The Eclipse Foundation AISBL
 </p>
 <h1 id="title">Dataspace Protocol NEXT</h1>
 <section id='abstract'>
diff --git a/specifications/catalog/catalog.binding.https.md b/specifications/catalog/catalog.binding.https.md
@@ -37,11 +37,11 @@ Authorization: ...</pre>
     </pre>
 </aside>
 
-- The `Authorization` header is optional if the [=Catalog Service=] does not require authorization. If present, the
+- 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 MAY contain an implementation-specific filter
+- The `filter` property is OPTIONAL. If present, the `filter` property MAY 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.
 
@@ -68,7 +68,7 @@ Authorization: ...</pre>
     </pre>
 </aside>
 
-- The `Authorization` header is optional if the [=Catalog Service=] does not require authorization. If present, the
+- 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**
@@ -85,7 +85,7 @@ a [Dataset](#ack-dataset).
 
 ### Pagination
 
-A [=Catalog Service=] may paginate the results of a [Catalog Request Message](#catalog-request-message). Pagination data
+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.
@@ -128,7 +128,7 @@ Link: <https://provider.com/catalog?continuationToken=bn9556075bn44de8ab4bfc9014
 
 ### Compression
 
-[=Catalog Services=] may compress responses to
+[=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).
 
diff --git a/specifications/catalog/catalog.protocol.md b/specifications/catalog/catalog.protocol.md
@@ -65,7 +65,7 @@ provided in protocol-dependent forms, e.g., for an HTTPS binding in the request
 | **Example**    | [Catalog Example](message/example/catalog.json)                                  |
 | **Properties**      | <p data-include="message/table/rootcatalog.html" data-include-format="html"></p> |
 
-- A [=Catalog=] MUST have zero to many [=Datasets=]. (_NOTE: 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=]._)
+- A [=Catalog=] MUST have zero to many [=Datasets=]. (_NOTE: 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=]._)
 
 - A [=Catalog=] MUST have one to many [=Data Services=] that reference a [=Connector=] where [=Datasets=] MAY be obtained.
 
@@ -94,7 +94,7 @@ An [=Offer=] contains the following attributes:
 
 - An [=Offer=] MUST be unique to a [=Dataset=] since the target of the [=Offer=] is derived from its enclosing context.
 
-- [=Offers=] MAY contain any `target` attributes. The value of the `target` attribute MUST be the [=Dataset=] identifier. (_NOTE: If the [=Offer=] is used in an enclosing [=Catalog=] or [=Dataset=], there must not be any `target` attribute set._)
+- [=Offers=] MAY contain any `target` attributes. The value of the `target` attribute MUST be the [=Dataset=] identifier. (_NOTE: If the [=Offer=] is used in an enclosing [=Catalog=] or [=Dataset=], there MUST NOT be any `target` attribute set._)
 
 ### ERROR - Catalog Error
 
@@ -112,7 +112,7 @@ a [Dataset Request Message](#dataset-request-message) and the [=Provider=] canno
 
 ### Queries and Filter Expressions
 
-A [=Catalog Service=] may support [=Catalog=] queries or filter expressions as an
+A [=Catalog Service=] MAY support [=Catalog=] queries or filter expressions as an
 implementation-specific feature. However, query capabilities by the [=Consumer=] MUST be implemented 
 against the results of a [Catalog Request Message](#catalog-request-message). Client-side querying can
 be scaled by periodically crawling
@@ -133,7 +133,7 @@ a [=Consumer=] discovers [=Catalog Services=].
 ### Security
 
 [=Catalog Services=] SHOULD implement access control. 
-A [=Catalog=] as well as individual [=Datasets=] may be restricted to trusted
+A [=Catalog=] as well as individual [=Datasets=] MAY be restricted to trusted
 parties. Therefore, the [=Catalog Service=] MAY
 require [=Consumers=] to include a security token along with
 a [Catalog Request Message](#catalog-request-message). The specifics of how this is done can be found in the relevant
@@ -146,14 +146,14 @@ If a [=Catalog=] contains protected [=Datasets=], the [=Provider=] has two optio
 all [=Datasets=] in the [=Catalog=] response and restrict access when a [=Policy=] is
 negotiated; or, require one or more proofs when the [Catalog Request](#catalog-request-message) is made and filter
 the [=Datasets=] accordingly. The latter option requires a mechanism for clients to
-discover the type of proofs that may be presented at request time. The specifics of proof types and presenting a proof
+discover the type of proofs that MAY be presented at request time. The specifics of proof types and presenting a proof
 during a [=Catalog=] request is outside the scope of the [=Dataspace Protocol=].
 However, [=Catalog Protocol=] bindings SHOULD define a proof data endpoint for
 obtaining this information.
 
 ### Catalog Brokers
 
-A [=Dataspace=] may include Catalog Brokers. A Catalog Broker is
+A [=Dataspace=] MAY include Catalog Brokers. A Catalog Broker is
 a [=Consumer=] that has trusted access to 1..N
 upstream [=Catalog Services=] and advertises their
 respective [=Catalogs=] as a
diff --git a/specifications/common/common.protocol.md b/specifications/common/common.protocol.md
@@ -3,7 +3,7 @@
 ## Authorization
 
 All requests to HTTPS endpoints SHOULD use the `Authorization` header to include an authorization token. The semantics
-of such tokens are not part of this specification. The `Authorization` HTTP header is optional if the [=Connector=]
+of such tokens are not part of this specification. The `Authorization` HTTP header is OPTIONAL if the [=Connector=]
 does not require authorization.
 
 ## Schemas & Contexts
@@ -18,7 +18,7 @@ similar contexts that facilitate this approach to interoperability. As this spec
 
 ## Exposure of Versions {#exposure-of-dataspace-protocol-versions}
 
-[=Connectors=] implementing the [=Dataspace Protocol=] may operate on different versions and bindings. Therefore, it is
+[=Connectors=] implementing the [=Dataspace Protocol=] MAY operate on different versions and bindings. Therefore, it is
 necessary that they can discover such information reliably and unambiguously. Each [=Connector=]
 MUST provide a version metadata endpoint ending with Uniform Resource Identifier (URI) segments `/.well-known/dspace-version`. The location of this 
 endpoint SHOULD adhere to [[rfc8615]].
diff --git a/specifications/common/terminology.md b/specifications/common/terminology.md
@@ -1,6 +1,6 @@
 # Terms and definitions {#terminology}
 
-The following terms and definitions introduce the core concepts, entities, and relationships that underpin a [=Dataspace=] and its communication protocols. Not all [=Dataspace=] entities have a concrete _technical_ materialization; some entities may exist as purely logical constructs.
+The following terms and definitions introduce the core concepts, entities, and relationships that underpin a [=Dataspace=] and its communication protocols. Not all [=Dataspace=] entities have a concrete _technical_ materialization; some entities MAY exist as purely logical constructs.
 
 <dfn>Agreement</dfn>
 
@@ -28,7 +28,7 @@ A [=Participant=] that requests access to an offered [=Dataset=].
 
 <dfn>Contract Negotiation</dfn>
 
-A set of interactions between a [=Provider=] and [=Consumer=] that establish an [=Agreement=]. It is an instantiation of the state machine of a [=Contract Negotiation Protocol=]. An outcome of a Contract Negotiation may be the production of an [=Agreement=].
+A set of interactions between a [=Provider=] and [=Consumer=] that establish an [=Agreement=]. It is an instantiation of the state machine of a [=Contract Negotiation Protocol=]. An outcome of a Contract Negotiation MAY be the production of an [=Agreement=].
 
 <dfn>Contract Negotiation Protocol</dfn>
 
diff --git a/specifications/negotiation/contract.negotiation.binding.https.md b/specifications/negotiation/contract.negotiation.binding.https.md
@@ -35,7 +35,7 @@ If the client is not authorized, the [=Consumer=] or [=Provider=] MUST return an
 ### Authorization
 
 All requests SHOULD use the `Authorization` header to include an authorization token. The semantics of such tokens are
-not part of this specification. The `Authorization` HTTP header is optional if the [=Connector=] does not require
+not part of this specification. The `Authorization` HTTP header is OPTIONAL if the [=Connector=] does not require
 authorization.
 
 ## Provider Path Bindings
@@ -93,7 +93,7 @@ Authorization: ...</pre>
   the [=Contract Negotiation=]. The HTTPS scheme MUST be supported. Implementations MAY optionally support other URL schemes.
 
 - Callback [=Messages=] will be sent to paths under the base URL as described by this specification. (_NOTE:
-  [=Providers=] should properly handle the cases where a trailing `/` is included
+  [=Providers=] SHOULD properly handle the cases where a trailing `/` is included
   with or absent from the `callbackAddress` when resolving full URL._)
 
 **Response**
@@ -110,7 +110,7 @@ the [Contract Negotiation](#ack-contract-negotiation):
 
 **Request**
 
-A [=Consumer=] may make an [=Offer=] by POSTing
+A [=Consumer=] MAY make an [=Offer=] by POSTing
 a [Contract Request Message](#contract-request-message)
 to `negotiations/:providerPid/request`:
 
@@ -254,7 +254,7 @@ Authorization: ...</pre>
   [=Contract Negotiation=]. The HTTPS scheme MUST be supported. Implementations MAY optionally support other URL schemes.
 
 - Callback messages will be sent to paths under the base URL as described by this specification. (_NOTE: [=Consumers=]
-  should properly handle the cases where a trailing / is included with or absent from the `callbackAddress` when
+  SHOULD properly handle the cases where a trailing / is included with or absent from the `callbackAddress` when
   resolving full URL._)
 
 **Response**
@@ -271,7 +271,7 @@ the [Contract Negotiation](#ack-contract-negotiation):
 
 **Request**
 
-A [=Provider=] may make an [=Offer=] by POSTing a [Contract Offer Message](#contract-offer-message) to
+A [=Provider=] MAY make an [=Offer=] by POSTing a [Contract Offer Message](#contract-offer-message) to
 the `negotiations/:consumerPid/offers` callback:
 
 <aside class="example" title="Contract Offer Request">
diff --git a/specifications/negotiation/contract.negotiation.protocol.md b/specifications/negotiation/contract.negotiation.protocol.md
@@ -99,7 +99,7 @@ a [Contract Request Message](#contract-request-message) sent by a [=Consumer=].
 - The [=Dataset=] identifier MAY be included when the [=Provider=] initiates a [=Contract Negotiation=].
 
 - Different to a [=Dataset=],
-  the [=Offer=] inside a [Contract Offer Message](#contract-offer-message) MUST have a `target` attribute. However, its contained Rules MUST not
+  the [=Offer=] inside a [Contract Offer Message](#contract-offer-message) MUST have a `target` attribute. However, its contained Rules MUST NOT
   have any `target` attributes to prevent inconsistencies with
   the [ODRL inferencing rules for compact policies](https://www.w3.org/TR/odrl-model/#composition-compact).
 
@@ -166,7 +166,7 @@ When the Contract Negotiation Event Message is sent by a [=Provider=] with an `e
 an [=Agreement=] has been finalized and the associated [=Dataset=] is accessible. The state machine is transitioned to
 the `FINALIZED` state.
 
-- Other event types may be defined in the future.
+- Other event types MAY be defined in the future.
 
 - A [=Consumer=] MUST respond with an error if the [=Agreement=] cannot be validated or is incorrect.
 
@@ -202,7 +202,7 @@ provide a description to help the receiver.
 
 - If an error is received in response to the message, the sending party MAY choose to ignore the error.
 
-Note that a [=Contract Negotiation=] may be terminated for a variety of reasons, for example, an unrecoverable error was encountered or one of
+Note that a [=Contract Negotiation=] MAY be terminated for a variety of reasons, for example, an unrecoverable error was encountered or one of
 the parties no longer wishes to continue. A [=Connector=]'s operator MAY
 remove terminated [=Contract Negotiation=] resources after it has reached the terminated state.
 
diff --git a/specifications/transfer/transfer.process.protocol.md b/specifications/transfer/transfer.process.protocol.md
@@ -51,7 +51,7 @@ responses, parameters, possible recursions, and interactions between the compone
 
 ##### Finite and Non-Finite Data
 
-Data may be `finite` or `non-finite`. This applies to either push and pull transfers. Finite data is data that is
+Data MAY be `finite` or `non-finite`. This applies to either push and pull transfers. Finite data is data that is
 defined by a finite set, for example, machine learning data or images. After finite data transmission has finished, the
 [=Transfer Process=] is completed. Non-finite data is data that is defined by an infinite set or has no specified end, for example,
 streams or an API endpoint. With non-finite data, a [=Transfer Process=] will continue indefinitely until either the [=Consumer=]
@@ -100,15 +100,15 @@ The Transfer Request Message is sent by a [=Consumer=] to initiate a [=Transfer
 - The `format` property is a format specified by a `Distribution` for the [=Dataset=] associated with
   the [=Agreement=]. This is generally obtained from the [=Provider=]'s [=Catalog=].
 
-- The `dataAddress` property MUST only be provided if the `format` requires a push transfer.
+- The `dataAddress` property MUST only be provided if the `format` REQUIRES a push transfer.
 
 - The `dataAddress` MUST contain a transport-specific set of properties for pushing the data. It MAY include an `endpoint`, 
   a temporary authorization via the `endpointProperties` property - depending on the `endpointType`.
 
-- `callbackAddress` MUST be a URI indicating where messages to the [=Consumer=] should be sent. If the address is not
+- `callbackAddress` MUST be a URI indicating where messages to the [=Consumer=] SHOULD be sent. If the address is not
   understood, the [=Provider=] MUST return an **unrecoverable** error.
 
-- The `endpointProperties` MAY (among others) contain the following optional values:
+- The `endpointProperties` MAY (among others) contain the following OPTIONAL values:
     - `authorization` - An opaque authorization token that clients MAY present when accessing the transport-specific
       endpoint address.
     - `authType` - The auth token type. For example, the value MAY be `bearer`. If present, this value MAY be used in
@@ -142,9 +142,9 @@ The Transfer Start Message is sent by the [=Provider=] to indicate the data tran
 
 - The `dataAddress` MUST be provided if the current transfer is a pull transfer and contains a transport-specific
   endpoint address for obtaining the data. The kind of transport is signaled by the `endpointType` property which
-  determines a set of required `endpointProperties` in a [=Profile=] separate from this specification.
+  determines a set of REQUIRED `endpointProperties` in a [=Profile=] separate from this specification.
 
-- The `endpointProperties` MAY (among others) contain the following optional values:
+- The `endpointProperties` MAY (among others) contain the following OPTIONAL values:
   - `authorization` - An opaque authorization token that clients MAY present when accessing the transport-specific
     endpoint address.
   - `authType` - The auth token type. For example, the value MAY be `bearer`. If present, this value MAY be used in
@@ -192,7 +192,7 @@ need to be sent.
 | **Properties**      | <p data-include="message/table/transferterminationmessage.html" data-include-format="html"></p> |
 
 The Transfer Termination Message is sent by the [=Provider=] or [=Consumer=] at any point except a terminal state to
-indicate the [=Transfer Process=] should stop and be placed in a terminal state. If the termination was due to an error, the sender MAY
+indicate the [=Transfer Process=] SHOULD stop and be placed in a terminal state. If the termination was due to an error, the sender MAY
 include error information.
 
 ## Response Types
