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 can use different tools that take care of essential technical aspects. Nonetheless, in the following we will briefly explain the correct JSON-LD syntax of an 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:

To simplify the human-readability for all openMINDS users, technical properties specifically required for the JSON-LD syntax are, on purpose, not defined in the openMINDS schema templates. 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 why these technical JSON-LD properties are needed.

The JSON-LD property "@type" expects an entry (value) of type string that defines which schema is used to validate the particular JSON-LD. Within openMINDS each schema can be identified through its namespace (type) 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 (e.g., ContactInformation), respectively.

The JSON-LD property "@id" expects an entry (value) of type string that provides a unique identifier for the created metadata instance. On your local machine, you should use the following naming convention 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. Within the EBRAINS Knowledge Graph (KG) this identifier has to be a universally unique identifier (UUID). Assuming you locally generated a openMINDS metadata collection, your user-defined "@id" will be automatically replaced with a UUID in all your JSON-LDs if they are uploaded to the KG.

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 to write a valid JSON-LD for an openMINDS metadata instance and how you can link different openMINDS metadata instances. 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

For users with at least some programming experience, one possible way to write openMINDS conform JSON-LDs is to use the openMINDS Python API.

The openMINDS spreadsheet templates

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

The Knowledge Graph Editor

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