Version: 1.0

Last Upate: 20.12.2023

About

This document specifies the Turntable API for Metadata Repositories. The Turntable API acts as a facade for (multiple) (metadata) repositories.

Target audience

This specification is targeted at people who:

build clients that should work with multiple (metadata) repositories.

About us

Research Data Management is part of the RWTH Aachen University.

Data Expoitation Methods (DEM), is part of the Scientific Computing Center (SCC), located at Karlsruhe Institute of Technology (KIT).

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Specification of the Interface

Forword

The interface implements the Digital Object Identifier Protocol (DOIP). It specifies one additional operation due to validate metadata documents. Implementation is based on SDK provided by DONA foundation.

Specification

The DataCite Schema (JSON Schema) is used for the metadata of the Digital Objects(DOs).

Authentication

Creating/Accessing digital objects may be restricted to authorized users only. For authentication and authorization JWT is supported right now.

Operations

This chapter describes the possible operations. It is splitted in two parts:

Basic Operations Operations which has to be implemented by all metadata repositories.
Extended Operations Operations which may be implemented by a metadata repository.

Basic Operations

All basic operations are specified in the specification published by DONA. If there are further requirements they will be mentioned here. Otherwise there are no further requirements.

0.DOIP/Op.Hello

see specification

0.DOIP/Op.Create

The service supports two different types of Digital Objects:

Metadata Documents (JSON, JSON-LD, XML)
Metadata Schema Documents (JSON-LD, JSON Schema, XSD)

Create a Metadata Document

While creating a metadata document the DO has to contain two elements:

Serialization of metadata (DataCite Schema(JSON))
- id = metadata
- type = application/json
Serialization of metadata document
- id = document
- type = application/ld+json | application/json | application/xml

(DataCite) Metadata

The dataCite metadata for creating a DO of a metadata document must contain the following fields:

titles
publisher
formats
relatedIdentifiers
- IsDescribedBy
- IsMetadataFor

Some fields are filled by server. See also here for further information.

formats

Defines the format of the metadata document

application/ld+json -> JSON LD
application/json -> JSON
application/xml -> XML

relatedIdentifiers

Identifier for

Schema Document -> type: IsDescribedBy
Digital Object(DO) -> type: IsMetadataFor

Many identifiers are supported. Most relevant are (in alphabetical order):

DOI
Handle
PURL
URL

Create a Schema/Application Profile

While creating a schema/AP the DO has to contain two elements:

Serialization of metadata (DataCite Schema(JSON))
- id = datacite
- type = application/json
Serialization of schema/AP
- id = application_profile | schema
- type = application/ld+json | application/json | application/xml

(DataCite) Metadata

The dataCite metadata for creating a DO of a schema/application profile must contain the following fields:

titles
publisher
formats

Some fields are filled by server. See also here for further information.

formats

Defines the format of the schema

application/ld+json -> Application Profile
application/json -> JSON Schema
application/xml -> XSD

0.DOIP/Op.Search

see specification Search Queries depend on underlying repository.

0.DOIP/Op.ListOperations

see specification

Extended Operations

0.DOIP/Op.Validation

This operation validates the provided metadata document with a registered schema. Attributes has to contain one property:

schema/AP - Identifier of schema/AP

DO has to contain one element with the serialization of the metadata document:

id = document
type= application/ld+json | application/json | application/xml

Return

0.DOIP/Status.001 - Validation was successful
0.DOIP/Status.xxx - An error occurred.

DataCite Schema

Entry	Description
identifiers	Identifier of the DO
creators	Creator of the DO
titles	Title of the DO
publisher	Publisher of the DO
publicationYear	Publication year of the DO
formats	Mimetype of the content.
relatedIdentifiers	Related DOs.
	Mandatory relation types:
	- IsMetadataFor: Identifier of the data
	- IsDescribedBy: Identifier of the schema/AP
schemaVersion	expected value: "http://datacite.org/schema/kernel-4"

Metadata of a Schema Document / Application Profile

The metadata or a schema document/application profile may contain the following fields:

Entry	Description
identifiers	Identifier of the DO
creators	Creator of the DO
titles	Title of the DO
publisher	Publisher of the DO
publicationYear	Publication year of the DO
formats	Mimetype of the content.
schemaVersion	expected value: "http://datacite.org/schema/kernel-4"

Examples

On the following pages you'll find two examples:

Create a Schema/Application Profile
Create a Metadata Document

Create a Schema/Application Profile

While creating a schema/AP the DO has to contain two elements:

Serialization of metadata (DataCite (JSON))
- id = metadata
- type = application/json
Serialization of schema/AP
- id = application_profile | schema
- type = application/ld+json | application/json | application/xml

Metadata

Entry	Provided	Mandatory	Description
identifiers	no	no	Will be intantiated by the server
creators	yes	no	If no creator is provided it will be filled with the entry found in authentication
titles	yes	yes	Title of the schema/application profile
publisher	yes	yes	Publisher of the schema/application profile
publicationYear	yes	no	If not provided actual year will be set
formats	yes	yes	Mimetype of the content.
			Possible values:
			- application/ld+json
			- application/json
			- application/xml
schemaVersion	yes	no	If not provided actual kernel version will be set

formats

Defines the format of the schema

application/ld+json -> Application Profile
application/json -> JSON Schema
application/xml -> XSD

Minimal DataCite Example (Ingesting an XSD document)

The DataCite metadata must contain the following fields:

{
  "identifiers": [
    {
      "identifierType": "URL",
      "identifier": "https://example.org/metastore/metadata/identifier"
    }
  ],
  "creators": [
    {
      "name": "Smith, Jane"
    }
  ],
  "titles": [
    {
      "title": "Minimal example for a(n) (XSD) schema document"
    }
  ],
  "publisher": "NFDI4Ing",
  "publicationYear": "2021",
  "formats": [
    "application/xml"
  ],
  "types": {
    "resourceTypeGeneral": "Other",
    "resourceType": "XML"
  },
  "schemaVersion": "http://datacite.org/schema/kernel-4"
}

Create a Metadata Document

While creating a metadata document the DO has to contain two elements:

Serialization of metadata (DataCite (JSON))
- id = metadata
- type = application/json
Serialization of metadata (document)
- id = document
- type = application/ld+json | application/json | application/xml

Metadata

Entry	Provided	Mandatory	Description
identifiers	no	no	Will be intantiated by the server
creators	yes	no	If no creator is provided it will be filled with the entry found in authentication
titles	yes	yes	Title of the metadata document
publisher	yes	yes	Publisher of the metadata document
publicationYear	yes	no	If not provided actual year will be set
formats	yes	yes	Mimetype of the content.
			Possible values:
			- application/ld+json
			- application/json
			- application/xml
relatedIdentifiers	yes	yes (both)	Related DOs.
			Supported relation types:
			- IsMetadataFor: Identifier of the data
			- IsDescribedBy: Identifier of the schema/AP
schemaVersion	yes	no	If not provided actual kernel version will be set

formats

Defines the format of the schema

application/ld+json -> JSON LD
application/json -> JSON
application/xml -> XSD

Minimal DataCite Examples (Ingesting an XML document)

The DataCite metadata must contain the following fields:

{
  "identifiers": [
    {
      "identifierType": "URL",
      "identifier": "https://example.org/metastore/metadata/identifier"
    }
  ],
  "creators": [
    {
      "name": "Smith, Jane"
    }
  ],
  "titles": [
    {
      "title": "Minimal example for a(n) (XML) metadata document"
    }
  ],
  "publisher": "NFDI4Ing",
  "publicationYear": "2021",
  "formats": [
    "application/xml"
  ],
  "types": {
    "resourceTypeGeneral": "Other",
    "resourceType": "XML"
  },
  "relatedIdentifiers": [
    {
      "relatedIdentifier": "https://example.org/datarepository/identifier",
      "relatedIdentifierType": "URL",
      "relationType": "IsMetadataFor",
    }, 
    {
      "relatedIdentifier": "https://example.org/metastore/schema/identifier",
      "relatedIdentifierType": "URL",
      "relationType": "IsDescribedBy",
    }
  ],
  "schemaVersion": "http://datacite.org/schema/kernel-4"
}

Specification of Turntable API for Metadata Repositories