JSON-LD - the openMINDS serialization format

As stated above, openMINDS supports JSON-LD as serialization format for the metadata representations (instances) of its schemas. For JSON-LD newbies: please do not be scared! Although you can, you do not have to write the JSON-LDs manually, but instead use different supportive software tools (see next sections). Nonetheless, for your benefit, we will briefly explain now the complete JSON-LD syntax of a correctly instantiated openMINDS instance.

Let us start with the most simple example: the openMINDS core schema ContactInformation. According to its schema template (cf. ContactInformation HTML), the only required property for a contact information instance is "email". However, every valid JSON-LD needs a couple more technical properties. Here, as example, a valid JSON-LD for a contact information instance:

These additional technical properties specifically required for the JSON-LD syntax are, on purpose, not defined in the openMINDS schema templates in order to simplify the human-readability for all users. Instead, these technical properties are first added to the required property list of all openMINDS schemas after their template is transformed into an established, full-blown metadata schema format, such as JSON-Schema (cf. Technical details). Let us explain in the following why these technical JSON-LD properties are needed and how they are correctly provided for an openMINDS instance.

The JSON-LD properties "@context" and "@vocab" define a common vocabulary mapping, by stating a prefix that extends all non-JSON-LD property names and "@type" values that do not correspond to an IRI or compact IRI. Within openMINDS, each metadata instance should map to the openMINDS vocabulary, meaning the "@context" and "@vocab" is the same across all metadata instances (cf. code above). If you want to learn more about the power of the openMINDS vocabulary please go to: Technical details.

Generally speaking, the JSON-LD property "@type" defines which schema should be used to validate the particular JSON-LD. The "@type" expects an entry (value) of type string with the format of an IRI. Within openMINDS, the "@type" value equals the corresponding schema-namespace with the following naming convention:

"@type": "https://openminds.ebrains.eu/XXX/YYY"

where XXX and YYY should be replaced with the openMINDS sub-module (e.g., core) and corresponding schema-name (e.g., ContactInformation), respectively.

In return, the JSON-LD property "@id" defines the particular metadata instance (node). For this reason, the "@id" also expects an entry (value) of type string with the format of an IRI. In particular when you plan to submit your metadata collection later to the EBRAINS Knowledge Graph, we recommend you use the following naming convention on your local machine for this identifier:

"@id": "http://localhost/YYY/ZZZ"

where YYY and ZZZ should be replaced with the openMINDS schema (e.g., ContactInformation) and your own collection-unique identifier (e.g. email_openMINDS), respectively. While locally this instance identifier only has to be unique within your collection or system, it has to be globally unique if you want to share your instances with the world. Within the EBRAINS Knowledge Graph (KG) this identifier is therefore replaced with an universally unique identifier (UUID) with integration of your openMINDS collection into the public graph database.

The JSON-LD property "@id" is also used to link two different metadata instances. Let us introduce a second openMINDS instance of the openMINDS core schema Person which can link to an openMINDS instance of the openMINDS core schema ContactInformation. Here a valid JSON-LD for a person with a link to the contact information we defined above:

Note that we do not use all properties defined for the schema (cf. the Person HTML), but that we only used the required property "givenName" and two optional properties "familyName" and "ContactInformation". Please also note, that a person is allowed to link to multiple contact information instances, hence it expects a list of dictionaries, instead of a single dictionary (which would be valid if only a single link is expected). 

You learned now how a valid JSON-LD for an openMINDS metadata instance looks like and how linkages between openMINDS instances are defined. In the following sections you will learn about the different tools that support you to create your own openMINDS JSON-LD metadata collection.

The openMINDS Python API

One possible way to write openMINDS conform JSON-LDs is to use the openMINDS Python API which will help you to interact with the EBRAINS openMINDS metadata models and schemas. It consists of two sub-modules:  

The openMINDS.generator (coming soon) facilitates the translation of the openMINDS schema template syntax to other established formats, such as HTML and JSON-Schema (cf. also Technical details).

The openMINDS.compiler allows you the dynamic usage of openMINDS metadata models and schemas in your Python application for generating your own collection of openMINDS conform metadata representations (instances) as JSON-LDs (as described above). Please note that the openMINDS.compiler only helps you to generate correctly formatted JSON-LD metadata instances - the preparation on how you want to describe your research product with openMINDS is still up to you. If you need support in designing your own openMINDS metadata collection, check out the Tutorials which might give you hints on how to tackle your individual case or, of course, get in touch with us via openminds@ebrains.eu.

Installation

The official versions are available at the Python Package Index and can be installed using `pip install` in your console:

The latest development version is available on the openMINDS generator GitHub.

openMINDS.compiler documentation

As stated above, the openMINDS.compiler allows you the dynamic usage of openMINDS metadata models and schemas in your Python application for generating your own collection of openMINDS conform metadata representations (instances) as JSON-LDs. Here a small example:

To learn in general about the available openMINDS metadata models and schemas including their required or optional metadata properties, please check out the HTML representations of the schemas (cf. Metadata models & schemas) or the code on the corresponding GitHub.

Interactively you can also get an overview of the requirement of a schema and all its properties by using the help_ function of the openMINDS.compiler. Here an example:

The openMINDS spreadsheet templates

(coming soon) For users with no programming experience, it is possible to provide at least openMINDS conform metadata by using the openMINDS spreadsheet templates.

The EBRAINS Knowledge Graph Editor

For curators of the EBRAINS Data & Knowledge service, it is possible to register openMINDS conform metadata into the EBRAINS Knowledge Graph database by using the EBRAINS Knowledge Graph Editor.