1.  Introduction

This document aims to guide the expert groups through the process of writing a technical specification for data space building blocks. A technical specification is a detailed description of the requirements, design, and functionality of a particular system, product, or service. In the context of DSSC, a technical specification serves as the Data Spaces Blueprint for creating interoperable and reusable components that can be used to build data spaces.

This document provides a set of templates that the expert groups can use to create a technical specification for data space building blocks. By following the guidelines outlined in this document and using these templates, in particular, WP5 of the DSSC  will be able to create clear and concise input for the Data Spaces Blueprint that captures the requirements and design for the Blueprint. This will help ensure creating interoperable and reusable components that can be easily integrated with other components across building blocks.

The first chapter defines the templates for the technical building blocks. The last chapter defines a similar template specified for the governance, business model, and legal building blocks.

 

2.  Technical Specification Template for Technical Data Space Building Blocks

2.1.                Front matter

To ensure consistency, it is recommended to reuse the existing DSSC word template for papers with covers, imprint, and content[1]. However, it should be extended to include important details such as the name/number of the expert group, the names of the reviewers, the date it was created, and the date it was last updated. This will provide a structured format for the front matter of the document.

Title: [Title of the document]

Publisher: [Name of the publisher]

Copyright: [Copyright information]

Consortium: [Name of the consortium]

Contact: [Contact information]

Author(s): [Name(s) of the author(s)]

Expert Group: [Name of the expert group]

Reviewers: [Name(s) of the reviewers]

Created On: [Date the document was created]

Last Updated: [Date the document was last updated]

2.2.                Introduction

Please note that the functional specification layer already acts as an introduction of the building block. You can use this chapter to highlight briefly the most important points from the functional layer: (1) purpose of the building block, (2) defined functionality, and (3) conclusions/future work.

2.3.                Technical Requirements

This section outlines the technical requirements for the data space building block, including factors required to deliver the desired functionality or behaviour from the components. For example, security features, compliance with standards, usability and accessibility requirements etc.

There are typically three types of technical requirements that we distinguish between. These include:

Business Requirements: These requirements are high-level and are taken from the business case of the data space building block. For example, the building block shall ensure semantic interoperability within a data space. 

**[Provide business requirements in the table below]**

 

Architectural and design requirements: These requirements are more detailed than business requirements and determine the overall design necessary to implement the business requirements. For example, the building block shall provide a vocabulary interface that allows all participants to be compliant and semantic interoperable.

**[Provide architectural and design requirements in the table below]**

 

 

System and integration requirements: these requirements are the most detailed level of requirements, providing a thorough description of every aspect. These requirements should provide developers with the necessary information and detail to start coding. For example, the building block shall use standard vocabularies and ontologies to ensure semantic interoperability. Therefore, the interface should also support the mapping of non-standard vocabularies to existing standard ones to ensure semantic interoperability among participants.

**[Provide system and integration requirements in the table below]**

 

To obtain additional information and create an accurate requirement, please refer to Software Requirements Analysis with Example (guru99.com).

2.4.                Process Model

This section should provide a detailed explanation of each component of the data space building block, including what each component does, what results can be expected, and what interfaces it should have. The following section elaborates on the design of these components, with a specific focus on establishing and developing.  

Furthermore, this section should also provide a generic basic process model for the data space building block, including information on when interfaces are used. It should specify the interactions taking place between the different components within the building block and across building blocks. It should provide a comprehensive understanding of the building block's process model.

Process model of the Building Block: It is important to define the different activities or process that are involved in the building block. This should be done by using UML Activity Diagrams. UML Activity Diagrams are graphical representations that show how activities are coordinated to provide or achieve a service or complete a process. For more information about UML Activity Diagrams, please consult the following webpage: What is Activity Diagram? (visual-paradigm.com).  

The process model should include multiple UML Activity Diagrams of the different activities or processes in the following two scenario’s:

o   Scenario 1 ‘Happy flow’:

o   This scenario represents the state where all components are functioning as intended. Meaning that all expected operations are successfully completed without any hours.  

 

o   Scenario 2..N ‘Exceptions/error’:

o   These diagrams should capture the different processes in case one or more components fail to function as intended. For example, what are the processes in case expected operations may fail or produce incorrect results? Or what happens if the dependent building blocks yield incorrect/unexpected results?

 

**[Illustrative image or figure describing the UML Activity Diagram for scenario 1 and 2]** 

2.5.                Component Design

In this section, the specified requirements and the defined processes in the previous section are mapped onto this section, resulting in the technical core of this building block. In many building blocks, components already exist and need to be integrated to ensure interoperability, or they may need to be developed or modified to meet specific requirements. In the case of components in the data space building block, it should define  clear and precise interfaces between components and ensure that they work seamlessly together. This entails the establishment of standardized protocols for designing components and/or facilitating their interaction with other components. For instance, this may involve integrating XACML technology in a Connector for Access Control or employing standardized API specifications to interact with a Clearing House implementation. These standardization efforts help ensure seamless integration and interoperation between different components, facilitating the development of scalable and flexible components.

Standardized protocols for designing components: Utilize industry standards and best practices in component design. It ensures compatibility and interoperability with other components, and it's important to utilize industry standards and best practices in component design. This includes adhering to relevant protocols, and data formats.

Defining interactions with other building blocks: In the previous section, assumptions were made about the different components, expected input and output. This section should define all the detailed interactions.  It should elaborate on the identification of the inputs and outputs of interacting with other components, as well as any dependencies for its operation. Please see the guidelines and the table provided below.

o   Related functionality as defined in the functional specifications.

o   Clearly list the interactions points (as assumptions):

o   For example: Building Block 2 do expect at [point in time] that BB3 will share [some information] with me in [format x].

o   Provide for each interaction what happens if the information is not shared or is incorrect? So, again, a scenario that captures the exceptions/errors.

 

Table 3: Interactions points with other building blocks

Create standardized API specifications with other building blocks:

For each interaction, the exact API specifications should be detailed. By specifying these details up front, it is easier to ensure interoperability between building blocks.  

Additionally, it may be necessary to revisit and update these assumptions and API specifications as the building block evolves or new interactions are identified. Note: ensure that the assumptions made, and the API specifications defined are consistent with the overall goals and requirements of the data space building block.

To detail API specifications, the OpenAPI specification standard can be used. The OpenAPI specification is a machine-readable format for describing RESTful API’s[2].

Endpoints & methods: Define the endpoints and methods for the API specification. Endpoints will be available for other components in actors to interact with the implementation of this specific building block. An endpoint is essentially a URL that points to a specific resource, and a method is the type of HTTP request that can be made to that endpoint, such as GET, POST, PUT, or DELETE.

Expected input and output formats: Specify the expected input and output formats for each endpoint.

 

Behaviour in response to different inputs and conditions: Define the expected behaviour of the API in response to different inputs and conditions. This includes specifying how the API will handle errors, invalid inputs, and unexpected inputs.

For each interaction, add a standardized API definition according to Getting Started | OpenAPI Documentation (oai.github.io). Please take a look at Smart Connected Supplier Network - API Specifications (smart-connected.nl) as example on how to specify a simple OpenAPI specification.

2.6.                Candidate Specifications and Reference Implementations

Together with WP4, a list of candidate standards, specifications and reference implementations is identified relevant for this building block. This section pertains to reference implementations that conform to the standards of compliance for this building block.

2.7.                Open Challenges – Future Roadmap

This section highlights any open challenges or future directions for the data space building block, including potential improvements. Potential challenges for a building block may arise in its interactions with other building blocks, making compliance a crucial consideration. This section should provide an overview of potential challenges and opportunities for future development of the building block.

2.8.                Conclusions

Short statements about the current state-of-the-art, how it matches with the defined requirements and functionality (gap analysis), and some final remarks.

 

 

[1] DSSC Word template for papers with cover, imprint, content.dotx

[2] OpenAPI Specification - Version 3.0.3 | Swagger