diff --git a/README.md b/README.md index 03c4cc8..96d023d 100644 --- a/README.md +++ b/README.md @@ -23,3 +23,6 @@ Further guidelines on how to create issues is currently under development. This repository does contain some general requirements (as markdown file) for the usage of metadata profiles in general. Moreover, there will be more markdown files to target metadata for special types of data sets - each having their own scope and requirements. +You can find non-functional requirements [here](non-functional-requirements.md). + +The requirements file for each respective module can be found in this [subfolder](modules/). diff --git a/modules/README.md b/modules/README.md new file mode 100644 index 0000000..94c31d8 --- /dev/null +++ b/modules/README.md @@ -0,0 +1,3 @@ +# Modules directory +In this directory you find the requirements files for all existing metadata modules. +You can use the github interface to look into the different markdown documents. diff --git a/modules/time-series.md b/modules/time-series.md new file mode 100644 index 0000000..47fc42e --- /dev/null +++ b/modules/time-series.md @@ -0,0 +1,22 @@ +# Time series module + +A time series is a mapping of a point or range in time towards a value. The value at this point can be a scalar / primitive or multidimensional. + +## Scope + +This module is focusing explicitly on any type of data set that is a mapping as described above. +It does specify the characteristics of the represented data. +It can link to additional modules like sensor information or database information if applicable. + +## Requirements + +### 1) Available data time interval +The time period for which data exists must be specifiable. + +### 2) Time resolution +The time resolution of the mappings needs to be specifiable. +This also applies if it changes over time e.g. through reduction after a given age. + +### 3) Specification of data content +The data values of each time point need to be specified in their shape and used units. + diff --git a/non-functional-requirements.md b/non-functional-requirements.md index c4c052b..d12059d 100644 --- a/non-functional-requirements.md +++ b/non-functional-requirements.md @@ -1,10 +1,10 @@ # Non-functional requirements -Metadata can come in many different flavors and therefore should allow to be used in multiple contexts. +Metadata can come in numerous flavors and therefore should allow to be used in multiple contexts. ## 1) Supported serialization formats -In general, metadata in a RDF format is preferred since it enables it to be stored in triple store databases. +In general, metadata in an RDF format is preferred since it enables it to be stored in triple store databases. This means the preferred serialization formats are RDF/XML, JSON-LD, Turtle, N3 and Ntriples. @@ -12,4 +12,64 @@ Nevertheless, other standardized formats as XML, JSON, YAML and TOML are also va ## 2) Provided schema files -Schema files shall be provided as Turtle/Notation3 and as JSON schema. Both for standard JSON and JSON-LD?! +Schema files shall be provided as Turtle/Notation3 and as JSON schema. +Both for standard JSON and JSON-LD?! + +## 3) Modularity + +Metadata should be tailored specifically for the type of data being annotated. +Many metadata fields are not relevant to a slightly different data set. +As a result, each metadata module / profile must have a precise and limited scope. +Smaller is often better in this context. +This means each data set is likely to require multiple metadata modules / profiles to be properly annotated. +A strategy to find relevant will eventually be published by our working group. + +## 4) Standard reuse + +There are many metadata standards around focusing on different use cases. +Whenever possible a metadata field or even profile should be reused from existing standards. +This can be done by using the respective GUPRIs (Globally Unique Persistent Resolvable Identifier) of the existing terms. + +## 5) Online documentation + +Each metadata module / profile and each individual metadata field shall have a definition and description text that is available online. + +## 6) Formalized specification + +The metadata schema needs to be available in a formalized way such that it can be used for validation and form generation purposes. + +## 7) Language + +The language used to specify metadata modules / profiles and metadata fields must be English. +If the formalization supports multiple languages other languages can be added as well, but English needs to be the one with the highest priority. + +## 8) Tooling + +### 8.1) Schema Editing + +The metadata schema shall be stored on github in a dedicated repository in the NFDI4Energy organization. + +The core schema shall be edited in Protege. + +### 8.2) Analysis and Validation + +Each new release of the schema must be checked with analysis tools to avoid design flaws and other smells. + +At this point a list of recommended tools will be added in the future. + +### 8.3) Conversion + +Only one formal specification of the metadata schema can be considered to root schema. +Any other potential schema serialization must be generated from this root specification. +An example for this would be the generation of JSON schema files from an OWL formalization. + +## 9) Versioning + +The metadata schema must be versioned using git tags. +This way, the persistent URLs for the schema files include the respective version number. +A new version shall come with a migration script to convert existing entries to a newer version of the schema. + +## 10) Usage guide + +The metadata schema needs to be accompanied by an online documentation or guide on how to use it properly. +This shall include different user perspectives including but not limited to data owners, application developers and data registry maintainers.