docs: 22-restructure-document-following-iso-style (#58)

* docs: Adding default ISO/IEC foreword to the document * docs: adding introduction section and removing from README.md * docs: adding scope section and removing from README.md * docs: adding default normative references from ISO template * docs: changing terminology to terms and definitions as required for ISO style * docs: Update model/terminology.md * docs: Update introduction.md * docs: removing external references as required by ISO guidance --------- Co-authored-by: Jim Marino <jim.marino@gmail.com> Co-authored-by: Arno Weiß <86715435+arnoweiss@users.noreply.github.com>
eclipse-dataspace-protocol-base · Nov 28, 2024 · 11a6735 · 11a6735
1 parent 7a2cf16
commit 11a6735
Show file tree

Hide file tree

Showing 7 changed files with 102 additions and 50 deletions.
diff --git a/README.md b/README.md
@@ -15,56 +15,11 @@ This version ([2024-1](https://github.com/International-Data-Spaces-Association/
 
 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](./model/terminology.md#agreement), and access data as part of a federation of technical systems termed a [Dataspace](./model/terminology.md#dataspace).
 
-## Introduction
-
-Sharing data between autonomous entities requires the provision of metadata to facilitate the transfer of [Datasets](./model/terminology.md#dataset) by making use of a data transfer (or application layer) protocol.
-The __Dataspace Protocol__ defines how this metadata is provisioned:
-
-1. How [Datasets](./model/terminology.md#dataset) are deployed as [DCAT Catalogs](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog) and usage control is expressed as [ODRL Policies](https://www.w3.org/TR/odrl-model/).
-2. How [Agreements](./model/terminology.md#agreement) that govern data usage are syntactically expressed and electronically negotiated.
-3. How [Datasets](./model/terminology.md#dataset) are accessed using [Transfer Process Protocols](./model/terminology.md#transfer-process-protocol).
-
-These specifications build on protocols located in the [ISO OSI model (ISO/IEC 7498-1:1994)](https://www.iso.org/standard/20269.html) layers, like HTTPS.
-The purpose of this specification is to define interactions between systems independent of such protocols, but describing how to implement it in an unambiguous and extensible way.
-To do so, the messages that are exchanged during the process are described in this specification and the states and their transitions are specified as state machines, based on the key terms and concepts of a [Dataspace](./model/terminology.md#dataspace).
-On this foundation the bindings to data transfer protocols, like HTTPS, are described.
-
-The specifications are organized into the following documents:
-
-* [__*Dataspace Model*__](./model/model.md) and [__*Dataspace Terminology*__](./model/terminology.md) documents that define key terms.
-* [__*Common Functionalities*__](./common/common.protocol.md) and their [__*Binding in HTTPS*__](./common/common.binding.https.md) declares cross-cutting functions as, e.g., the declaration of supported versions of this Dataspace Protocol.
-* [__*Catalog Protocol*__](./catalog/catalog.protocol.md) and [__*Catalog HTTPS Binding*__](./catalog/catalog.binding.https.md) documents that define how [DCAT Catalogs](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog) are published and accessed as HTTPS endpoints respectively.
-* [__*Contract Negotiation Protocol*__](./negotiation/contract.negotiation.protocol.md) and [__*Contract Negotiation HTTPS Binding*__](./negotiation/contract.negotiation.binding.https.md) documents that define how [Contract Negotiations](./model/terminology.md#contract-negotiation) are conducted and requested via HTTPS endpoints.
-* [__*Transfer Process Protocol*__](./transfer/transfer.process.protocol.md) and [__*Transfer Process HTTPS Binding*__](./transfer/transfer.process.binding.https.md) documents that define how [Transfer Processes](./model/terminology.md#transfer-process) using a given data transfer protocol are governed via HTTPS
-  endpoints.
-
-> **This specification does not cover the data transfer process as such.**
->
-> While the data transfer is controlled by the __*Transfer Process Protocol*__ mentioned above, e.g. the initation of the transfer channels or their decomissioning, the data transfer itself and especially the handling of technical exceptions is an obligation to the Transport Protocol.
->
-> As an implication, the data transfer can be conducted in a separated process if required, as long as this process is to the specified extend controlled by the __*Transfer Process Protocol*__.
->
-> Nevertheless, illustrative message examples are provided in the [__*Transfer Process Protocol section*__](./transfer/transfer.process.protocol.md#2-message-types). The best practices section may contain further non-normative examples and explanations.
-
-### Context of this specification
-
-The __Dataspace Protocol__ is used in the context of [Dataspaces](./model/terminology.md#dataspace) as described and defined in the subsequent sections with the purpose to support interoperability.
-In this context, the specification provides fundamental technical interoperability for [Participants](./model/terminology.md#participant) in [Dataspaces](./model/terminology.md#dataspace).
-Beyond the technical interoperability measures described in this specification, semantic interoperability should also be addressed by the [Participants](./model/terminology.md#participant). On the perspective of the [Dataspace](./model/terminology.md#dataspace), interoperability needs to be addressed also on the level of trust, on organizational levels, and on legal levels.
-The aspect of cross-dataspace communication is not subject of this document, as this is addressed by the [Dataspaces'](./model/terminology.md#dataspace) organizational and legal agreements.
 
-The interaction of [Participants](./model/terminology.md#participant) in a [Dataspace](./model/terminology.md#dataspace) is conducted by the [Participant Agents](./model/terminology.md#participant-agent), so-called [Connectors](./model/terminology.md#connector--data-service-), which implement the protocols described above.
-While most interactions take place between [Connectors](./model/terminology.md#connector--data-service-), some interactions with other systems are required.
-The figure below provides an overview on the context of this specification.
+* [Introduction to the Dataspace Protocol](./introduction.md)
+* [Scope of the Dataspace Protocol](./scope.md)
 
-An [Identity Provider](./model/terminology.md#identity-provider) realizes the required interfaces and provides required information to implement the Trust Framework of a [Dataspace](./model/terminology.md#dataspace).
-The validation of the identity of a given [Participant Agent](./model/terminology.md#participant-agent) and the validation of additional claims is a fundamental mechanism. The structure and content of such claims and identities may, however, vary between different [Dataspaces](./model/terminology.md#dataspace), as well as the structure of such an [Identity Provider](./model/terminology.md#identity-provider), e.g. a centralized system, a decentralized system or a federated system. Other specifications, like the Identity and Trust Protocol ([IATP](https://github.com/eclipse-tractusx/identity-trust)), define the respective functions.
-
-A [Connector](./model/terminology.md#connector--data-service-) will implement additional internal functionalities, like monitoring or policy engines, as appropriate. It is not covered by this specification if a [Connector](./model/terminology.md#connector--data-service-) implements such or how.
-
-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")
+## Introduction
 
 ## Best Practices
 

diff --git a/foreword.md b/foreword.md
@@ -0,0 +1,22 @@
+# Foreword
+
+ISO (the International Organization for Standardization) is a worldwide federation of national standards bodies (ISO member bodies). The work of preparing International Standards is normally carried out through ISO technical committees. Each member body interested in a subject for which a technical committee has been established has the right to be represented on that committee. International organizations, governmental and non-governmental, in liaison with ISO, also take part in the work. ISO collaborates closely with the International Electrotechnical Commission (IEC) on all matters of electrotechnical standardization.
+
+The procedures used to develop this document and those intended for its further maintenance are described in the ISO/IEC Directives, Part 1. In particular, the different approval criteria needed for the different types of ISO documents should be noted. This document was drafted in accordance with the editorial rules of the ISO/IEC Directives, Part 2 (see [www.iso.org/directives](www.iso.org/directives)).
+
+ISO draws attention to the possibility that the implementation of this document may involve the use of (a) patent(s). ISO takes no position concerning the evidence, validity or applicability of any claimed patent rights in respect thereof. As of the date of publication of this document, ISO **[had/had not]** received notice of (a) patent(s) which may be required to implement this document. However, implementers are cautioned that this may not represent the latest information, which may be obtained from the patent database available at [www.iso.org/patents](www.iso.org/patents). ISO shall not be held responsible for identifying any or all such patent rights.
+
+Any trade name used in this document is information given for the convenience of users and does not constitute an endorsement.
+For an explanation of the voluntary nature of standards, the meaning of ISO specific terms and expressions related to conformity assessment, as well as information about ISO's adherence to the World Trade Organization (WTO) principles in the Technical Barriers to Trade (TBT), see [www.iso.org/iso/foreword.html](www.iso.org/iso/foreword.html).
+
+**This document was prepared by Technical Committee [or Project Committee] ISO/TC [or ISO/PC] ###, [name of committee], Subcommittee SC ##, [name of subcommittee].**
+
+**This second/third/… edition cancels and replaces the first/second/… edition (ISO #####:####), which has been technically revised.**
+
+**The main changes are as follows:**
+
+**—	xxx xxxxxxx xxx xxxx**
+
+A list of all parts in the **ISO #####** series can be found on the ISO website.
+
+Any feedback or questions on this document should be directed to the user’s national standards body. A complete listing of these bodies can be found at [www.iso.org/members.html](www.iso.org/members.html).
diff --git a/index.html b/index.html
@@ -49,7 +49,16 @@ <h1 id="title">Dataspace Protocol</h1>
     </p>
 </section>
 
-<section data-include="README.md" data-include-format="markdown">
+<section data-include="foreword.md" data-include-format="markdown">
+</section>
+
+<section data-include="introduction.md" data-include-format="markdown">
+</section>
+
+<section data-include="scope.md" data-include-format="markdown">
+</section>
+
+<section data-include="normative.references.md" data-include-format="markdown">
 </section>
 
 <section data-include="model/terminology.md" data-include-format="markdown">

diff --git a/introduction.md b/introduction.md
@@ -0,0 +1,19 @@
+# Introduction
+
+The __Dataspace Protocol__ is used in the context of [Dataspaces](./model/terminology.md#dataspace) as described and defined in the subsequent sections with the purpose to support interoperability.
+In this context, the specification provides fundamental technical interoperability for [Participants](./model/terminology.md#participant) in [Dataspaces](./model/terminology.md#dataspace).
+Beyond the technical interoperability measures described in this specification, semantic interoperability should also be addressed by the [Participants](./model/terminology.md#participant). On the perspective of the [Dataspace](./model/terminology.md#dataspace), interoperability needs to be addressed also on the level of trust, on organizational levels, and on legal levels.
+The aspect of cross-dataspace communication is not subject of this document, as this is addressed by the [Dataspaces'](./model/terminology.md#dataspace) organizational and legal agreements.
+
+The interaction of [Participants](./model/terminology.md#participant) in a [Dataspace](./model/terminology.md#dataspace) is conducted by the [Participant Agents](./model/terminology.md#participant-agent), so-called [Connectors](./model/terminology.md#connector--data-service-), which implement the protocols described above.
+While most interactions take place between [Connectors](./model/terminology.md#connector--data-service-), some interactions with other systems are required.
+The figure below provides an overview on the context of this specification.
+
+An [Identity Provider](./model/terminology.md#identity-provider) realizes the required interfaces and provides required information to implement the Trust Framework of a [Dataspace](./model/terminology.md#dataspace).
+The validation of the identity of a given [Participant Agent](./model/terminology.md#participant-agent) and the validation of additional claims is a fundamental mechanism. The structure and content of such claims and identities may, however, vary between different [Dataspaces](./model/terminology.md#dataspace), as well as the structure of such an [Identity Provider](./model/terminology.md#identity-provider), e.g. a centralized system, a decentralized system or a federated system. Other specifications define the respective functions.
+
+A [Connector](./model/terminology.md#connector--data-service-) will implement additional internal functionalities, like monitoring or policy engines, as appropriate. It is not covered by this specification if a [Connector](./model/terminology.md#connector--data-service-) implements such or how.
+
+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")
diff --git a/model/terminology.md b/model/terminology.md
@@ -1,4 +1,4 @@
-# Terminology
+# Terms and definitions {#terminology}
 
 This and the following sections define the core concepts, entities, and relationships that underpin a __dataspace__ and its protocol.
 

diff --git a/normative.references.md b/normative.references.md
@@ -0,0 +1,17 @@
+# 2. Normative references
+
+_Two options of text (remove the inappropriate option)._
+
+**1) The normative references shall be introduced by the following wording.**
+
+The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.
+
+ISO ##### #, General title — Part #: Title of part
+
+ISO ##### ##:20##, General title — Part ##: Title of part
+
+ISO/IEC 22123-1, Information technology — Cloud computing — Part 1: Vocabulary
+
+**2) If no references exist, include the following phrase below the clause title:**
+
+There are no normative references in this document.
diff --git a/scope.md b/scope.md
@@ -0,0 +1,30 @@
+# Scope
+
+Sharing data between autonomous entities requires the provision of metadata to facilitate the transfer of [Datasets](./model/terminology.md#dataset) by making use of a data transfer (or application layer) protocol.
+The __Dataspace Protocol__ defines how this metadata is provisioned:
+
+1. How [Datasets](./model/terminology.md#dataset) are deployed as [DCAT Catalogs](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog) and usage control is expressed as [ODRL Policies](https://www.w3.org/TR/odrl-model/).
+2. How [Agreements](./model/terminology.md#agreement) that govern data usage are syntactically expressed and electronically negotiated.
+3. How [Datasets](./model/terminology.md#dataset) are accessed using [Transfer Process Protocols](./model/terminology.md#transfer-process-protocol).
+
+These specifications build on protocols located in the [ISO OSI model (ISO/IEC 7498-1:1994)](https://www.iso.org/standard/20269.html) layers, like HTTPS.
+The purpose of this specification is to define interactions between systems independent of such protocols, but describing how to implement it in an unambiguous and extensible way.
+To do so, the messages that are exchanged during the process are described in this specification and the states and their transitions are specified as state machines, based on the key terms and concepts of a [Dataspace](./model/terminology.md#dataspace).
+On this foundation the bindings to data transfer protocols, like HTTPS, are described.
+
+The specifications are organized into the following documents:
+
+* [__*Dataspace Model*__](./model/model.md) and [__*Dataspace Terminology*__](./model/terminology.md) documents that define key terms.
+* [__*Common Functionalities*__](./common/common.protocol.md) and their [__*Binding in HTTPS*__](./common/common.binding.https.md) declares cross-cutting functions as, e.g., the declaration of supported versions of this Dataspace Protocol.
+* [__*Catalog Protocol*__](./catalog/catalog.protocol.md) and [__*Catalog HTTPS Binding*__](./catalog/catalog.binding.https.md) documents that define how [DCAT Catalogs](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog) are published and accessed as HTTPS endpoints respectively.
+* [__*Contract Negotiation Protocol*__](./negotiation/contract.negotiation.protocol.md) and [__*Contract Negotiation HTTPS Binding*__](./negotiation/contract.negotiation.binding.https.md) documents that define how [Contract Negotiations](./model/terminology.md#contract-negotiation) are conducted and requested via HTTPS endpoints.
+* [__*Transfer Process Protocol*__](./transfer/transfer.process.protocol.md) and [__*Transfer Process HTTPS Binding*__](./transfer/transfer.process.binding.https.md) documents that define how [Transfer Processes](./model/terminology.md#transfer-process) using a given data transfer protocol are governed via HTTPS
+  endpoints.
+
+> **This specification does not cover the data transfer process as such.**
+>
+> While the data transfer is controlled by the __*Transfer Process Protocol*__ mentioned above, e.g. the initation of the transfer channels or their decomissioning, the data transfer itself and especially the handling of technical exceptions is an obligation to the Transport Protocol.
+>
+> As an implication, the data transfer can be conducted in a separated process if required, as long as this process is to the specified extend controlled by the __*Transfer Process Protocol*__.
+>
+> Nevertheless, illustrative message examples are provided in the [__*Transfer Process Protocol section*__](./transfer/transfer.process.protocol.md#2-message-types). The best practices section may contain further non-normative examples and explanations.