1 of 10

A very brief introduction to �making metadata with JSON-LD

1

This work is licensed under a �Creative Commons Attribution 4.0 International License.

Stian Soiland-Reyes

The University of Manchester

Abigail Miller

The Jackson Laboratory

2 of 10

2

Let me start by framing the problem that JSON-LD is designed to solve.

The web today is filled with information , but much of it is messy, disconnected, and isolated.

JSON-LD, which stands for JavaScript Object Notation for Linked Data, is built on top of JSON , a format that's already widely used by developers , but adds a layer of semantic meaning that allows data to be linked and connected across domains and systems.

At its core, JSON-LD is about enabling Linked Data , a way of connecting data points using global identifiers, usually in the form of URLs. This allows systems to traverse from one dataset to another, building a network of knowledge.

Think of it like hyperlinks for data: just like you can click a link on a webpage to get more information, Linked Data lets software follow links between datasets to understand people, places, concepts, and relationships. In this example, we describe John Lennon , including his name, date of birth, and spouse , using identifiers that link to external sources like DBpedia. A machine can read this and then fetch more context from those linked resources.

JSON-LD helps bridge the gap between isolated data silos and a truly connected web of data. It's a core building block for modern metadata strategies like RO-Crate.

3 of 10

Benefits of JSON-LD

When using JSON-LD, we’re not just formatting data,

we’re giving it meaning

Semantic clarity

Links data to well-defined concepts using vocabularies like schema.org.

Allows disambiguating terms like “name” by giving them context

Interoperability

Enables consistent data exchange across systems, APIs, and the web

Machine and human readable

Retains the readability of JSON while providing structure that can be parsed by machines

Prepares data for LLM integration

Organizing data in JSON-LD gives it clear structure and meaning, making it easier for LLMs to understand and reason about

JSON-LD allows us to define exactly what each term means by linking it to a shared vocabulary like schema.org.�For example, the word “name” could refer to a person, a company, or a file—JSON-LD removes that ambiguity by assigning it a precise meaning.�This semantic context helps both machines and humans interpret the data consistently.

Because JSON-LD uses standard identifiers and linked vocabularies, it makes your data portable and understandable across platforms.�Whether you’re working with web services, APIs, or research repositories, the data stays meaningful and usable.�This is especially useful when integrating with external systems or aligning with web standards.

JSON-LD builds on regular JSON, so it's easy for developers to read and write by hand if needed.�At the same time, its structure is rich enough for machines to parse, analyze, and even validate.�This dual readability makes it ideal for applications that need both transparency and automation.

When data is structured with clear semantics—as in JSON-LD—LLMs can more easily understand what each part of the data means.�This improves the model’s ability to reason about the data, link related information, and generate more accurate, context-aware responses.�In other words, JSON-LD is a natural fit for the next generation of intelligent tools.

4 of 10

4

"@type": "LearningResource",

{ "@context": "https://schema.org/",

Type (identifier implied)

Metadata about training material

Nested object

with its own @type and attributes

"name": "Adding nanomaterial data",

"version": "0.9.3",

"description": "This tutorial describes how nanomaterial data can be added to an eNanoMapper server using a RDF format.",

"license": "https://creativecommons.org/licenses/by/4.0/",

"keywords": "ontologies, enanomapper, RDF",

"url": "https://nanocommons.github.io/tutorials/enteringData/",

"provider": {

"@type": "Organization",

"name": "NanoCommons",

"url": "https://www.nanocommons.eu/"

},

"…": {}

}

JSON-LD context

"provider": {

"@type": "Organization",

"name": "NanoCommons",

"url": "https://www.nanocommons.eu/"

},

"http://purl.org/dc/terms/conformsTo": {

"@type": "CreativeWork",

"@id": "https://bioschemas.org/profiles/TrainingMaterial/1.0-RELEASE"

},

Bioschemas profile

https://nanocommons.github.io/tutorials/enteringData/ �by Egon Willighagen

Let’s begin with a basic JSON-LD structure.�At the top, we define the @context, usually set to https://schema.org/, which gives meaning to the keys used in the object. The @context in JSON-LD defines the meaning of the terms used in the data by linking them to well-known vocabularies, enabling consistent interpretation by both humans and machines.�We also define a type , here it's LearningResource , and provide metadata such as the name, version, description, license, and keywords.

The conformsTo property in JSON-LD indicates that the described resource follows a specific standard or profile, helping consumers understand how the data is structured and how to validate or interpret it.

JSON-LD allows us to nest objects.�For example, the provider here is described as an organization with its own @type, name, and url.�This is more expressive than just using plain strings.�We’re describing not just the metadata about a resource, but the entities related to it.

5 of 10

RO-Crate Metadata File

5

{ "@id": "cp7glop.ai",

"@type": "File",� "name": "Diagram showing trend to increase",

…

},

…

{ "@type": "CreativeWork",

"@id": "ro-crate-metadata.json",

"conformsTo": {"@id": "https://w3id.org/ro/crate/1.1"},

"about": { "@id": "./" }

}

{ "@context": "https://w3id.org/ro/crate/1.1/context",

"@graph": [

RO-Crate metadata file descriptor

RO-Crate root dataset

..collection of Data entities

..described w/ contextual entities

{ "@id": "./",

"identifier": "https://doi.org/10.5281/zenodo.1009240",

"@type": "Dataset",�

"hasPart": [

{ "@id": "cp7glop.ai" },

{ "@id": "lots_of_little_files/" },

{ "@id": "communities-2018.csv" },

{ "@id": "https://doi.org/10.4225/59/59672c09f4a4b" },

{ "@id": "SciDataCon Presentations/AAA_Pilot_Project_Abstract.html" }

],�

"author": { "@id": "https://orcid.org/0000-0002-8367-6908" },

"publisher": { "@id": "https://ror.org/03f0f6041" },

"citation": { "@id": "https://doi.org/10.1109/TCYB.2014.2386282"},

"name": "Presentation of user survey 2018"

},

Flat list of metadata per entity

JSON-LD preamble

"hasPart": [

{ "@id": "cp7glop.ai" },

{ "@id": "lots_of_little_files/" },

{ "@id": "communities-2018.csv" },

{ "@id": "https://doi.org/10.4225/59/59672c09f4a4b" },

{ "@id": "SciDataCon-Presentations/AAA_Pilot_Abstract.html"}

],

This slide illustrates a typical JSON-LD structure for an RO-Crate , a format used to package data with its metadata in a machine-readable and reusable way.

Top block , JSON-LD Preamble

We begin with the @context and @graph , this is the standard JSON-LD preamble.

The @context points to the RO-Crate 1.1 context, which defines how to interpret the terms in the document. In BioConnect we have an additional context that points to the ISA entity definitions.

The @graph contains a flat array of metadata entities. Each item in the graph represents a single object , such as the metadata file itself, the dataset, or a data file.

�

First object , RO-Crate Metadata File Descriptor

The first item in the @graph is the metadata descriptor, describing the file ro-crate-metadata.json.

The @type is CreativeWork, and we say that it conformsTo the RO-Crate 1.1 specification.

The "about" property links this metadata file to the root dataset using "@id": "./" , essentially pointing to the crate itself.

Second object , RO-Crate Root Dataset

This is the root dataset for the RO-Crate, representing the whole research object.

It has an @id of "./" and an identifier (in this case, a DOI).

The @type is "Dataset" , this tells us the nature of the object we're describing.

hasPart lists the main data entities included in the dataset. These can be files, folders, or even remote URLs. Each is referenced by its @id.

Descriptive metadata for the dataset

We also provide contextual information:

author: with an ORCID identifier

publisher: with a ROR ID

citation: pointing to a DOI

name: the human-readable title of the dataset

These properties make the dataset more discoverable, citable, and interoperable.

Third object , A File Entity

This is a metadata entry for one of the files listed in hasPart.

The @id is "cp7glop.ai", and it is typed as a File.

We give it a name , "Diagram showing trend to increase" , so humans can understand what it represents.

This pattern repeats for every file or resource in the crate.

6 of 10

Metadata

6

{

"@id": "https://orcid.org/0000-0002-8367-6908",

"@type": "Person",

"affiliation": { "@id": "https://ror.org/03f0f6041" },

"name": "J. Xuan"

}

{

"@id": "https://ror.org/03f0f6041",

"@type": "Organization",

"name": "University of Technology Sydney",

"url": "https://www.uts.edu.au/"

}

{

"@id": "figure.png",

"@type": ["File", "ImageObject"],

"name": "XXL-CT-scan of an XXL Tyrannosaurus rex skull",

"identifier": "https://doi.org/10.5281/zenodo.3479743",

"author": {"@id": "https://orcid.org/0000-0002-8367-6908"},

"encodingFormat": "image/png"

}

Linked Data: Reference by URI

Types and properties are expanded by context, e.g. http://schema.org/ImageObject

Entities can be cross-referenced with @id within the same JSON-LD document

Style Flattened JSON-LD: each entity is listed separately in @graph array. @id required

Style Compacted JSON-LD: the entity can be nested within any cross-reference, @id optional

Clients can still follow the links for potentially more data (e.g. ORCID lists publications)

7 of 10

Using common vocabularies

.. extending only when needed

8 of 10

8

https://schema.org/Dataset �is based on W3C DCAT

9 of 10

Testing in the JSON-LD Playground

9

https://json-ld.org/playground/

https://tinyurl.com/y9vc8vby

10 of 10

Testing in Schema Markup Validator

10

https://validator.schema.org/

This slide shows a real-world example of how we can validate our JSON-LD metadata using the Schema.org Validator.

On the left side, we see a snippet of JSON-LD metadata for a tutorial titled “Adding nanomaterial data”. This describes a LearningResource using the schema.org vocabulary.

We’re including:

Basic metadata like name, version, description, license, keywords, and url.

A provider object that describes the organization responsible , in this case, NanoCommons.

And importantly, a conformsTo field that shows this learning resource follows the Bioschemas TrainingMaterial profile. This is indicated using a CreativeWork object with an @id.

On the right side, you can see the validator successfully parsing all of these fields, displaying them as structured data.�You'll notice there are zero errors and zero warnings, which confirms that our JSON-LD is both syntactically valid and semantically meaningful.

This kind of validation is important for two reasons:

It helps you check your metadata before publishing, especially if search engines or external services will consume it.

It gives you confidence that your JSON-LD is interpreted the way you expect , particularly when using extensions like Bioschemas.

The Schema.org validator is free, lightweight, and very useful even for non-developers who want to review metadata quality.