Appearance
Use JSON-LD for heritage when your data needs to be both consumed by ordinary web developers and understood as linked data, especially for embedding in HTML pages, feeding APIs, or publishing schema.org markup. It is the right call when your audience speaks JSON, when you want one format that doubles as a plain data feed and a semantic graph, and when IIIF or web-API integration is on the table. It is the wrong call when humans must hand-edit the graph, when you are authoring ontologies, or when a tight RDF toolchain already standardises on Turtle.
What problem does JSON-LD actually solve?
JSON-LD lets you ship data that a JavaScript front-end treats as normal JSON while a semantic consumer reads as RDF. The trick is the @context, which maps human-friendly keys to full IRIs.
json
{
"@context": {
"title": "http://purl.org/dc/terms/title",
"creator": "http://purl.org/dc/terms/creator"
},
"@id": "https://data.example.org/object/00041523",
"title": "View of Delft",
"creator": "https://www.wikidata.org/entity/Q41264"
}A web team consumes title and creator directly; a triplestore expands them into Dublin Core triples. One file, two audiences.
When is JSON-LD the right choice?
Reach for it when the signals below line up:
- Your consumers are web developers or front-end frameworks expecting JSON.
- You want schema.org markup embedded in collection pages for discovery.
- You are building or consuming IIIF, whose Presentation API is JSON-LD natively.
- You need a format that serves as both a plain feed and an RDF graph.
- Your records are machine-generated, not hand-curated.
When should I avoid it?
JSON-LD is verbose and awkward to hand-edit. Avoid it when:
- Humans author or review the graph directly. Turtle is dramatically more readable.
- You are writing ontologies or SHACL shapes. Those communities live in Turtle.
- Deep nesting and blank nodes dominate; JSON-LD's framing gets fiddly.
- Your whole pipeline already standardises on N-Triples for streaming loads.
| Format | Best audience | Readability | Typical heritage use |
|---|---|---|---|
| JSON-LD | Web devs, APIs, IIIF | Moderate | Page embeds, feeds, manifests |
| Turtle | Modellers, editors | High | Ontologies, SHACL, hand editing |
| N-Triples | Loaders, diffs | Low | Bulk import, line-based tooling |
| RDF/XML | Legacy systems | Low | Compatibility only |
How do I avoid the @context trap?
The context is where meaning lives, and getting it wrong fails silently. A mistyped IRI maps your creator to nothing, so consumers see opaque JSON. Always check the expanded form, which strips the context and shows the literal triples.
bash
# using jsonld.js CLI or pyld
python -c "from pyld import jsonld, json; \
import sys,json as j; \
print(j.dumps(jsonld.expand(j.load(open('object.jsonld'))), indent=2))"If the expanded output does not show full IRIs as keys, your context is broken before anyone consumes the data.
Inline or remote context, which is safer?
A remote @context referenced by URL keeps payloads small and consistent across thousands of records, but it creates a single point of failure: if that URL goes offline or its contents change, every consumer can break at once. The pragmatic pattern is to host a versioned, pinned context and cache it, while still publishing a stable URL.
json
{ "@context": "https://data.example.org/context/v1.jsonld",
"@id": "https://data.example.org/object/00041523",
"title": "View of Delft" }Bump to v2.jsonld for breaking changes rather than mutating v1.
Does schema.org JSON-LD help discovery?
Embedding a schema.org block in each object page gives search engines and aggregators structured signals about creator, date and type. It will not by itself move rankings, but it improves how items can be parsed and surfaced.
html
<script type="application/ld+json">
{ "@context": "https://schema.org",
"@type": "VisualArtwork",
"name": "View of Delft",
"creator": { "@type": "Person", "name": "Johannes Vermeer" } }
</script>Key Takeaways
- JSON-LD shines when both web developers and semantic consumers need the same data.
- The
@contextcarries the meaning; validate the expanded form to confirm your triples. - Prefer Turtle for hand-editing, ontologies and SHACL; JSON-LD for APIs, embeds and IIIF.
- JSON-LD is a full RDF serialisation, including named graphs via
@graph. - Pin and version a remote context; never mutate a published one.
- schema.org JSON-LD aids discovery without guaranteeing ranking gains.
- If your consumers are humans editing triples, JSON-LD is the wrong fit.
Frequently Asked Questions
Is JSON-LD the same as plain JSON?
Almost. Valid JSON-LD is valid JSON, but it adds a @context that maps keys to IRIs so the data carries machine-readable semantics. A regular JSON consumer can ignore the context and still read the values.
When should I prefer Turtle or RDF/XML over JSON-LD?
Prefer Turtle when humans will read and hand-edit the graph, or for ontology and SHACL files, because it is far more compact and readable. Use RDF/XML only when a legacy tool demands it; JSON-LD wins when web developers and APIs are the consumers.
Does adding schema.org JSON-LD improve heritage SEO?
It can. Embedding schema.org JSON-LD in collection pages helps search engines and aggregators understand objects, creators and dates, which can enrich how results appear, though it does not guarantee ranking changes.
Can JSON-LD represent the same data as a full RDF triplestore?
Yes. JSON-LD is a complete RDF serialisation, so any triple you can store in a triplestore can be expressed in JSON-LD, including named graphs via the @graph keyword.
What is the cost of getting the @context wrong?
A wrong or missing context silently changes the meaning: keys map to the wrong IRIs or to none, so consumers either misinterpret your data or treat it as opaque JSON. Validate the expanded form to confirm the triples are what you intended.
Should the @context be inline or referenced by URL?
Reference a shared context by URL for consistency across many records and smaller payloads, but pin a versioned copy and cache it, because a context fetched at runtime that goes offline or changes can break every consumer at once.