From 567b7194c3ffb0c0abdf3e9000a52238186cbcda Mon Sep 17 00:00:00 2001 From: Sebastian Steinbuss <23654606+ssteinbuss@users.noreply.github.com> Date: Wed, 5 Nov 2025 15:46:51 +0100 Subject: [PATCH 1/2] fix: RFC 2119 keywords in uppercase Changing some RFC 2119 keywords to uppercase as expected. --- specifications/catalog/catalog.binding.https.md | 10 +++++----- specifications/catalog/catalog.protocol.md | 12 ++++++------ specifications/common/common.protocol.md | 4 ++-- specifications/common/terminology.md | 6 +++--- .../contract.negotiation.binding.https.md | 10 +++++----- .../negotiation/contract.negotiation.protocol.md | 6 +++--- .../transfer/transfer.process.protocol.md | 14 +++++++------- 7 files changed, 31 insertions(+), 31 deletions(-) diff --git a/specifications/catalog/catalog.binding.https.md b/specifications/catalog/catalog.binding.https.md index d289677..c1fd599 100644 --- a/specifications/catalog/catalog.binding.https.md +++ b/specifications/catalog/catalog.binding.https.md @@ -37,11 +37,11 @@ Authorization: ... -- 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: ... -- 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:

| -- 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 index 3668418..46931c6 100644 --- 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 index 97d43c1..8157b8b 100644 --- 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. Agreement @@ -28,7 +28,7 @@ A [=Participant=] that requests access to an offered [=Dataset=]. Contract Negotiation -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=]. Contract Negotiation Protocol @@ -48,7 +48,7 @@ Note 1 to entry: This specification convers only protocols to facilitate interop Dataspace Protocol -A set of [=Messages=] and [=Message=] sequences that enables the interaction between [=Participant Agents=] in a [=Dataspace=]. This may require additional concepts, which are not in the scope of the specification itself. +A set of [=Messages=] and [=Message=] sequences that enables the interaction between [=Participant Agents=] in a [=Dataspace=]. This MAY require additional concepts, which are not in the scope of the specification itself. Data Transfer Protocol diff --git a/specifications/negotiation/contract.negotiation.binding.https.md b/specifications/negotiation/contract.negotiation.binding.https.md index eb8bf2c..00420b9 100644 --- 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: ... 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: ... [=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: