The Allotrope Data Format (ADF) [ADF] consists of several APIs and taxonomies. This document constitutes the specification for the ADF Data Description (ADF-DD). It defines how to store meta data of Data Package and Data Cubes along with experimental or process data and contextual meta data. ADF-DD is based on semantic web and linked data concepts using the RDF Data Model.



Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current Allotrope publications and the latest revision of this technical report can be found in the Allotrope technical reports index at http://purl.allotrope.org/TR/.

This document is part of a set of specifications on the Allotrope Data Format [ADF]

This document was published by the Allotrope Foundation as a First Public Working Draft. This document is intended to become an Allotrope Recommendation. If you wish to make comments regarding this document, please send them to more.info@allotrope.org. All comments are welcome.

Publication as a First Public Working Draft does not imply endorsement by the Allotrope Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Table of Contents

1. Introduction

The Allotrope Data Format (ADF) defines an interface for storing scientific observations from analytical chemistry. It is intended for long-term stability of archived analytical data and fast real-time access to it. The ADF Data Description (ADF-DD) API defines an interface for storing functional and technical meta data.

The document is structured as follows: Next, the role of the ADF Data Description within the high-level structure of ADF is shown. Then, the requirements are listed, the core graph operations (query, insert, delete) are described.

Examples of the different operations are given in the Developer's Guide [ADF-DD-DG].

1.1 Document Conventions

1.1.1 Namespaces

Within this specification, the following namespace prefix bindings are used:

Prefix Namespace

1.1.2 Indication of Requirement Levels

Within this document the definitions of MUST, SHOULD and MAY are used as defined in [rfc2119].

1.1.3 Number Formatting

Within this document, decimal numbers will use a dot "." as the decimal mark.

2. ADF High-Level Structure

The following figure illustrates the high-level structure of the Allotrope Data Format (ADF) [ADF] API stack:

Fig. 1 The high-level structure of the Allotrope Data Format (ADF) API stack.

This document focuses on the ADF Data Description API.

3. Requirements

This section introduces the key requirements to the Allotrope Data Format Data Description (ADF-DD) API. They are summarized in the following list:

4. RDF Graph Operations

The Data Description API MUST provide functions for the core operations on the RDF graph - i.e. the data stored in the ADF triple store (ADF-QS) [ADF-QS].

The API of Apache Jena [APACHE-JENA] constitutes the ADF Data Description API. In the following sections, the core functions of the API are described, examples are given in the ADF Data Description API Developer's Guide [ADF-DD-DG]. For a complete description of the API, please consult the JavaDoc API documentation and the sources listed in the References section.

4.1 The RDF Graph

In Apache Jena, an RDF graph [RDF] is called a model and is represented by the Model interface [APACHE-JENA], [JENA-INTRO]. Basically, the Jena Model that represents the RDF graph consists of a set of statements (also called triples), where each statement consists of a subject, predicate and object. The following sections describe the basic operations on the RDF graph. For more details on the Jena API, it is referred to [APACHE-JENA] and [JENA-INTRO].

4.2 Querying an RDF Graph

The RDF graph MAY be queried by iterating over its statements or by executing SPARQL [SPARQL] queries on it.

4.3 Modifying an RDF Graph

The ADF-DD API MUST provide methods to modify the RDF Graph. 'Modify' means adding, removing and updating statements. Modification MUST be possible via the API and via SPARQL 1.1 UPDATE queries.

4.3.1 Inserting Statements into an RDF Graph

Statements MAY be created and inserted into the RDF graph either via the API method or via a SPARQL query using the INSERT operation. Note that in an RDF graph a statement is uniquely identified by its subject, predicate and object. Thus, if a statement already exists, no new statement MAY be created.

4.3.2 Removing a Statement from the RDF Graph

To remove statements from an RDF graph, the API method for removal MAY be used or a SPARQL query using the DELETE operation. For the latter, the removal with a SPARQL update query MAY optionally be based on a condition specified in a WHERE clause.

4.3.3 Updating a Statement in the RDF Graph

Updating statements in an RDF graph MAY be realized by combining INSERT and DELETE operations in one SPARQL Update query.

5. Change History

Version Release Date Remarks
0.3.0 2015-04-30 Initial Working Draft version
0.4.0 2015-06-29
  • included disclaimer information
  • harmonized layout across ADF specifications
  • harmonized structure across ADF specifications
  • moved all examples to the ADF-DD API Developer's Guide
1.0.0 2015-09-17 RC
  • added Indication of Requirement Levels section
  • enforced usage of specification specific keywords
  • replaced ADF-DD API User's Guide by ADF-DD API Developer's Guide
  • clarified the operations in section RDF Graph Operations
1.0.0 2015-09-29
  • updates versions, dates and document status
  • added captions to figures
1.1.0 RC 2016-03-11
  • updated versions, dates and document status
  • added section on number formatting to document conventions
  • updated Fig. 1
1.1.0 RF 2016-03-31
  • updated versions, dates and document status
1.1.5 2016-05-13
  • updated versions and dates
1.2.0 Preview 2016-09-23
  • updated versions and dates
1.2.0 RC 2016-12-07
  • updated versions and dates
  • changed reference from ADF-TS to ADF-QS
1.3.0 Preview 2017-03-31
  • updated versions and dates
1.3.0 RF 2017-06-30
  • updated versions and dates
  • updated images

A. References

A.1 Normative references

Allotrope. Allotrope Data Format Overview. URL: http://purl.allotrope.org/TR/adf-overview/Allotrope Data Format.html
W3C. RDF 1.1 Concepts and Abstract Syntax. URL: http://www.w3.org/TR/rdf11-concepts/
The World Wide Web Consortium. SPARQL 1.1 Update - W3C Recommendation 21 March 2013. URL: http://www.w3.org/TR/sparql11-update/
S. Bradner. IETF. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119

A.2 Informative references

Allotrope. ADF Data Description API Developer's Guide. URL: http://purl.allotrope.org/TR/adf-dd-dg/ADF Data Description Developer's Guide.html
Allotrope. ADF Quad Store API. URL: http://purl.allotrope.org/TR/adf-qs/ADF Quad Store API.html
The Apache Software Foundation. Apache Jena - A free and open source Java framework for building Semantic Web and Linked Data applications.. URL: https://jena.apache.org/
The Apache Software Foundation. Apache Jena - An Introduction to RDF and the Jena RDF API. URL: https://jena.apache.org/tutorials/rdf_api.html