Functional specifications

This living document forms the basis of Deliverable 3.1 that will guide the design and implementation of the platform.

Introduction

The intention of this living document is to reach a team consensus on what the EERAdata platform is to achieve. We expect that such consensus among the stakeholders is established step by step during the project implementation. Hereby, we draw on practices in professional software development with the purpose

• To specify the stakeholders´ needs. A Product Requirements Document (PRD) is a document containing all the requirements for a certain software product. It is written with direct user involvement to allow all stakeholders to understand what the product should do. A PRD, however, does not anticipate or define how the product will do it. In EERAdata we provide this by asking the project partners in their role as energy researchers for user stories, comprising concrete support needs for FAIR data in their use cases.

• To link requirements and functionality. The Functional Specifications Document (FSD) specifies the functions that a software must perform. A functional specification is a more technical response to the PRD. It does not define the inner workings of the proposed system, nor does it include the specification of how the system function will be implemented. Instead, it focuses on what various outside agents (people using the program, computer peripherals, or other computers, for example) might observe when interacting with the system. In EERAdata we achieve this by providing mock-ups, descriptions of the front-end features on the EERAdata Wiki and allowing test users to access preliminary platform implementations during development. In this way feedback can be collected continually from the consortium and from a wider community through the EERAdata workshops.

• To specify technical implementation options. A Software Requirements Specification (SRS) is a description of a software system to be developed. Typically, it is written by a technical writer, a systems architect, or a software programmer. Software requirements specification is a rigorous assessment of requirements before the more specific system design stages, and its goal is to reduce later redesign. It should also provide a realistic basis for estimating risks, schedules, and, in our case, future maintenance issues. I

Thus, in the following, three perspectives are considered - user needs, software design- and software implementation issues - in the development of the platform elements and in the use of the methods and tools.

Platform elements

Front end

Methods: user stories, design thinking, mock-ups, Wiki (voting)

Landing page

user authentication; user guide

Community forum

feedback on platform; discussion of content

Dashboard

queries

Session logging

for later performance monitoring

Processing and storage device

In the following figure, we sketch how metadata describing the thematic character of external databases may be harmonized for use in the EERAdata platform. A similar strategy could also be used to harmonize the metadata for the specific records in the databases; this would be conceptually similar, but with a more complicated structure to the records.

Three external databases are considered, and termed DB1, DB2, and DB3. They are each described in terms of a set of thematic classes following some standard classification, given in terms of persistent identifiers (pIDs) for the appropriate classes. DB1 and DB2 use the same standardization system, providing pIDs (Class-std1-ID) for the appropriate classes. DB3 uses a second standardization system, providing pIDs (Class-std2-ID) for its corresponding classes. We cannot assume the two systems to be commensurable.

Further, we cannot assume that either system is commensurable with the standardization system adopted for the EERAdata platform. Thus, instead of directly using the standards from the external databases, we harmonize the external standards to that used by the EERAdata platform. This is shown as the tables Std1-harmonization and Std2-harmonization, which constitute correspondence tables between the external pIDs and the pIDs used internally by EERAdata (EERAdata-std-ID). The correspondence tables must accurately relate standards that may be at different levels of precision and with different approaches to classification. It is thus essential that the tables are constructed with input from domain experts.

The correspondence tables allow us to describe the external databases in a consistent fashion using the internal standard for the platform. Needed detail is provided internally, e.g., giving a short class name and a description as shown in the figure. Beyond using the classes as a nomenclature for thematic content, ontological relations between the classes can be expressed, e.g., as a Class-hierarchy specifying which classes have others as subclasses, shown in the figure as pairings of pIDs for the classes along with their separation in the hierarachy. Crucially, it is not necessary to use the ontological structures of the external databases, although they must be accounted for in preparing the correspondence tables.

Back end

• Interfaces to external resources (APIs, …); communication with platform owners, support by Use Case Leaders required
• Interfaces to import metadata from external sources (provided by the Use Cases)
• Data preparation for front end
• …

Methods: software development, establishment of communication channels with database holders

Software system requirements

• Usability
• Graphic design
• Reliability
• Availability
• Adherence to IPRs
• Data protection
• Security
• Migration and future maintenance
• …

Methods and tools

To collect expectations and needs, we must account for different perspectives:

1. energy research expertise from use cases & gap analysis;
2. data science expertise from FAIR/O community; and
3. process expertise from standardisation community

Design thinking

Which tools will we use to create the mock-ups? Design suggestions are posted on the Wiki for voting and feedback within the project community.

Collection of user requirements

As a first step, the use case leaders and other use-case members are involved in formulating the needs and requirements. As an important tool, we plan to use user stories to be provided by them or other stakeholders from the energy research community. User stories put features in the context of what the user needs to accomplish. They describe the task or feature, but not how the developers should implement it. First step: invite Use Case leaders and members to collect user stories on the Wiki. Second step: approach external stakeholders for user stories (database holders, interoperability community…).