refactor: apply editorial changes (#202)

* docs: ensure consistent usage of abbreviations

* docs: add minor changes

* docs: align usage of "specification" as singular term

* docs: align modal verbs

* chore: apply change requests from review

* chore: remove italics from keywords

Author: juliapampus

README.md

@@ -1,6 +1,6 @@
 # Dataspace Protocol
 
-The __Dataspace Protocol__ is a set of specifications designed to facilitate interoperable data sharing between entities governed by usage control and based on Web technologies. These specifications define the schemas and protocols required for entities to publish data, negotiate [Agreements](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#dfn-agreement), and access data as part of a federation of technical systems termed a [Dataspace](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#dfn-dataspace).
+The __Dataspace Protocol__ is a specification designed to facilitate interoperable data sharing between entities governed by usage control and based on Web technologies. This specification defines the schemas and protocols required for entities to publish data, negotiate [Agreements](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#dfn-agreement), and access data as part of a federation of technical systems termed a [Dataspace](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#dfn-dataspace).
 
 The web rendering of the Dataspace Protocol represents the current state on this repo's main branch: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/.
 

artifacts/buildSrc/README.md

@@ -1,6 +1,6 @@
 # Introduction
 
-This directory contains the Schema Table Generator plugin. The plugin generates readable type information in HTML for Json
+This directory contains the Schema Table Generator plugin. The plugin generates readable type information in HTML for JSON
 schema definitions found in the project source set.
 
 For example:
@@ -56,7 +56,7 @@ the `aside` element in the appropriate Markdown file:
 
 ## Implementation notes
 
-The Json Schema Object Model parser does not yet support all Json Schema features such `anyOf` or `oneOf`.  
+The JSON Schema Object Model parser does not yet support all JSON Schema features such `anyOf` or `oneOf`.  
 
 # Build Setup
 

index.html

@@ -70,8 +70,8 @@
 <h1 id="title">Dataspace Protocol 2025-1-RC3</h1>
 <section id='abstract'>
     <p>
-        The Dataspace Protocol is a set of specifications designed to facilitate interoperable data sharing between
-        entities governed by usage control and based on Web technologies. These specifications define the schemas and
+        The Dataspace Protocol is a specification designed to facilitate interoperable data sharing between
+        entities governed by usage control and based on Web technologies. This specification defines the schemas and
         protocols required for entities to publish data, negotiate Agreements, and access data as part of a federation
         of technical systems termed a Dataspace.
     </p>
@@ -80,8 +80,8 @@ <h1 id="title">Dataspace Protocol 2025-1-RC3</h1>
     <p>
         This version (2025-1) of the Dataspace Protocol specification is a release of the specification and considered to be
         stable. Further changes shall not affect conformity. All changes made to the specification can be reviewed in
-        the GitHub repositories - up to and including `2024-1` under the governance of the <a href="https://github.com/International-Data-Spaces-Association/ids-specification">IDSA</a>
-        and with the <a href="https://github.com/eclipse-dataspace-protocol-base/DataspaceProtocol">EDWG</a> ever since.
+        the GitHub repositories - up to and including `2024-1` under the governance of the <a href="https://github.com/International-Data-Spaces-Association/ids-specification">International Data Spaces Association</a>
+        and with the <a href="https://github.com/eclipse-dataspace-protocol-base/DataspaceProtocol">Eclipse Dataspace Working Group</a> ever since.
     </p>
 </section>
 

specifications/catalog/catalog.binding.https.md

@@ -1,20 +1,20 @@
 # Catalog HTTPS Binding {#catalog-http}
 
-This specification defines a RESTful API over HTTPS for the [=Catalog Protocol=].
-
 ## Introduction
 
+This binding defines a RESTful Application Programming Interface (API) over HTTPS for the [=Catalog Protocol=].
+
 ### Prerequisites
 
 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.
+2. All request and response [=Messages=] MUST use the `application/json` media type.
 
 ### Catalog Error
 
-In the event of a request error, the [=Catalog Service=] must return an appropriate HTTP code and
+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.
 
 ## Path Bindings
@@ -41,13 +41,13 @@ Authorization: ...</pre>
   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
+- 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.
+  implementation, it MUST return a HTTP 400 (Bad Request) response.
 
 **Response**
 
-If the request is successful, the [=Catalog Service=] must return an HTTP 200 (OK) with a response body containing
+If the request is successful, the [=Catalog Service=] MUST return an HTTP 200 (OK) with a response body containing
 a [Catalog](#ack-catalog).
 
 <aside class="example" title="Catalog Response">
@@ -69,12 +69,11 @@ Authorization: ...</pre>
 </aside>
 
 - 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]]].
+  contents of the `Authorization` header are detailed in the [[[#authorization]]].
 
 **Response**
 
-If the request is successful, the [=Catalog Service=] must return an HTTP 200 (OK) with a response body containing
+If the request is successful, the [=Catalog Service=] MUST return an HTTP 200 (OK) with a response body containing
 a [Dataset](#ack-dataset).
 
 <aside class="example" title="Dataset Response">
@@ -87,9 +86,9 @@ a [Dataset](#ack-dataset).
 ### Pagination
 
 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.
+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.
+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:
@@ -129,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).
 

specifications/catalog/catalog.protocol.md

@@ -1,15 +1,13 @@
 # Catalog Protocol {#catalog-protocol}
 
-This document outlines the [=Catalog Protocol=]. The used terms are described in section [[[#terminology]]].
-
 ## Introduction
 
 The [=Catalog Protocol=] defines how a [=Catalog=] is requested from a [=Catalog Service=] by a [=Consumer=] using an
-abstract [=Message=] exchange format. The concrete [=Message=] exchange wire format is defined in the binding specifications.
+abstract [=Message=] exchange format. The concrete [=Message=] exchange wire format is defined in the binding.
 
 The [=Catalog Protocol=] reuses properties from the DCAT and ODRL vocabularies with restrictions defined in this
-specification. This is done implicitly by the use of the JSON schemas and JSON-LD-contexts that are part of the DSP.
-Servers have no obligation to process properties that are not part of the schemas.
+specification. This is done implicitly by the use of the JSON schemas and JSON-LD-contexts that are part of the [=Dataspace Protocol=].
+Servers MAY process properties that are not part of the schemas.
 
 ## Message Types
 
@@ -24,16 +22,15 @@ Servers have no obligation to process properties that are not part of the schema
 | **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=].
-The [=Catalog Service=] must respond with a [Catalog](#ack-catalog) that adheres to the schema linked above.
+The Catalog Request Message is sent by a [=Consumer=] to a [=Catalog Service=].
+The [=Catalog Service=] MUST respond with a [Catalog](#ack-catalog) that adheres to the schema linked above.
 
-- The message may have a `filter` property which contains an implementation-specific query or filter expression type
+- The message MAY have a `filter` property which contains an implementation-specific query or filter expression type
   supported by the [=Catalog Service=].
 
-- The [=Catalog Service=] may require an authorization token. Details for
+- The [=Catalog Service=] MAY require an authorization token. Details for
   including that token can be found in the protocol binding, e.g., [Catalog HTTPS Binding](#catalog-https-binding).
-  Similarly, pagination may be defined in the protocol binding.
+  Similarly, pagination MAY be defined in the protocol binding.
 
 ### Dataset Request Message
 
@@ -46,18 +43,17 @@ The [=Catalog Service=] must respond with a [Catalog](#ack-catalog) that adheres
 | **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=].
-The [=Catalog Service=] must respond with a [Dataset](#ack-dataset) that adheres to the schema linked above.
+The Dataset Request Message is sent by a [=Consumer=] to a [=Catalog Service=].
+The [=Catalog Service=] MUST respond with a [Dataset](#ack-dataset) that adheres to the schema linked above.
 
-- The message must have a `dataset` property which contains the id of the [=Dataset=].
+- The message MUST have a `dataset` property which contains the identifier of the [=Dataset=].
 
-- The [=Catalog Service=] may require an authorization token. Details for
+- The [=Catalog Service=] MAY require an authorization token. Details for
   including that token can be found in the protocol binding, e.g., [Catalog HTTPS Binding](#catalog-https-binding).
 
 ## Response Types
 
-The `ACK` and `ERROR` response types are mapped onto a protocol such as HTTPS. A description of an error might be
+The `ACK` and `ERROR` response types are mapped onto a protocol such as HTTPS. A description of an error MAY be
 provided in protocol-dependent forms, e.g., for an HTTPS binding in the request or response body.
 
 ### ACK - Catalog
@@ -69,8 +65,9 @@ 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 one to many [=Data Services=] that reference a [=Connector=] where [=Datasets=] may be obtained.
+- 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.
 
 ### ACK - Dataset
 
@@ -81,18 +78,23 @@ provided in protocol-dependent forms, e.g., for an HTTPS binding in the request
 | **Example**    | [Dataset Example](message/example/dataset.json)                               |
 | **Properties**      | <p data-include="message/table/dataset.html" data-include-format="html"></p> |
 
-* A [=Dataset=] _MUST_ have at least one `hasPolicy` attribute that contain an [=Offer=] defining the [=Policy=] associated with the [=Dataset=].
-* A [=Dataset=] _MUST_ hold at least one `Distribution` object in the `distribution` attribute.
-* Each `DataService` object _MUST HAVE_ at least one `DataService` which specifies where the distribution is obtained. 
+- A [=Dataset=] MUST have at least one `hasPolicy` attribute that contains an [=Offer=] defining the [=Policy=] associated with the [=Dataset=].
+
+- A [=Dataset=] MUST hold at least one `Distribution` object in the `distribution` attribute.
+
+- Each `DataService` object MUST have at least one `DataService` which specifies where the distribution is obtained. 
   Specifically, a `DataService` specifies the endpoint for initiating a [=Contract Negotiation=] and [=Transfer Process=].
-* A `DataService.endpointURL` property contains the URL of the service the Contract Negotiation endpoints extend. The
-  endpoint's DSP version MUST be consistent with the version the `Catalog` object was served through.
+
+- A `DataService.endpointURL` property contains the URL of the service the [=Contract Negotiation=] endpoints extend. The
+  endpoint's [=Dataspace Protocol=] version MUST be consistent with the version the `Catalog` object was served through.
 
 An [=Offer=] contains the following attributes:
 
-* An [=Offer=] _MUST_ have an `@id` that is a unique identifier.
-* An [=Offer=] _MUST_ be unique to a [=Dataset=] since the target of the [=Offer=] is derived from its enclosing context.
-* [=Offers=] _MUST NOT_ contain any `target` attributes. The value of the `target` attribute _MUST_ be the [=Dataset=] ID. (_Note: If the [=Offer=] is used in an enclosing [=Catalog=] or [=Dataset=], there must not be any `target` attribute set._)
+- An [=Offer=] MUST have an `@id` that is a unique identifier.
+
+- 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._)
 
 ### ERROR - Catalog Error
 
@@ -104,17 +106,15 @@ An [=Offer=] contains the following attributes:
 | **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.
+a [Dataset Request Message](#dataset-request-message) and the [=Provider=] cannot provide its [=Catalog=] to the requester.
 
 ## Technical Considerations
 
 ### Queries and Filter Expressions
 
 A [=Catalog Service=] may support [=Catalog=] queries or filter expressions as an
-implementation-specific feature. However, it is expected that query capabilities will be implemented by
-the [=Consumer=] against the results of
-a [Catalog Request Message](#catalog-request-message), as the latter is an RDF vocabulary. Client-side querying can
+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
 the [=Provider=]'s [=Catalog Services=], caching
 the results, and executing queries against the locally-stored [=Catalogs=].
@@ -132,24 +132,23 @@ a [=Consumer=] discovers [=Catalog Services=].
 
 ### Security
 
-It is expected (although not required) that [=Catalog Services=] implement access
-control. A [=Catalog=] as well as individual [=Datasets=] may be restricted to trusted
-parties. The [=Catalog Service=] may
+[=Catalog Services=] SHOULD implement access control. 
+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
 protocol binding, e.g., [Catalog HTTPS Binding](#catalog-https-binding). The semantics of such tokens are not part
 of this specification.
 
 #### The Proof Metadata Endpoint
 
-When a [=Catalog=] contains protected [=Datasets=]
-the [=Provider=] has two options: include
-all [=Datasets=] in the [=Catalog=] response and restrict access when a contract is
+If a [=Catalog=] contains protected [=Datasets=], the [=Provider=] has two options: include
+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
 during a [=Catalog=] request is outside the scope of the [=Dataspace Protocol=].
-However, [=Catalog Protocol=] bindings should define a proof data endpoint for
+However, [=Catalog Protocol=] bindings SHOULD define a proof data endpoint for
 obtaining this information.
 
 ### Catalog Brokers
@@ -158,5 +157,5 @@ 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
-single [=Catalog Service=]. The broker is expected to honor upstream access
-control requirements.
+single [=Catalog Service=]. The Catalog Broker SHOULD honor upstream access
+control requirements ([=Policies=]).