Wiki · Concept · Last reviewed June 25, 2026

JSON-LD

JSON-LD is the W3C JSON syntax for Linked Data: a way to give ordinary JSON terms web-scale meaning without pretending that machine readability is the same as truth.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: JSON-LD, linked data, agents, provenance, schema.org, web standards

Definition

JSON-LD is JSON for Linked Data. The W3C JSON-LD 1.1 Recommendation, published on July 16, 2020, defines it as a JSON-based serialization for Linked Data. Its practical promise is compatibility: a document can remain valid JSON while adding a context that maps local words to global identifiers.

The central object is the @context. It tells a processor what terms such as name, creator, homepage, or license mean by mapping them to IRIs. Other common keywords include @id for identifiers, @type for type information, @value for literal values, and @graph for graph data.

JSON-LD is not a database, ontology, credential, signature, crawler rule, or trust framework. It is a serialization and processing model. It can carry meaningful structured claims, but it does not prove those claims.

Mechanism

JSON-LD sits between ordinary JSON and RDF-style graph data. RDF Concepts describes RDF as a graph made of triples: subject, predicate, and object. JSON-LD lets JSON documents express that graph shape while remaining comfortable for web developers who already work with JSON.

The companion JSON-LD Processing Algorithms and API Recommendation defines transformations such as expansion, compaction, flattening, and RDF serialization or deserialization. Expansion makes compact terms explicit. Compaction makes expanded data readable under a chosen context. Flattening normalizes scattered nodes into a flatter graph view. Framing lets developers reshape graph data into a desired tree structure.

On the web, JSON-LD often appears as application/ld+json in a script element. Schema.org's developer documentation says machine-readable definitions of individual terms are available as embedded JSON-LD in term-page HTML, and it identifies the schema.org JSON-LD context file. That makes JSON-LD attractive for search, archives, crawlers, and agent-readable site metadata.

Agent Context

JSON-LD matters for agents because agents need more than fluent page text. A browsing agent, purchasing agent, research agent, or compliance crawler may need to know which thing a page describes, what identifiers attach to it, which organization published it, what action is being advertised, and which provenance or credential terms are being used.

The useful pattern is separation. Human-facing prose can say what a page means to readers. JSON-LD can expose structured claims for machines. A governing system can then log which JSON-LD document, context URL, vocabulary, timestamp, and parsed graph influenced the agent's decision.

That does not make JSON-LD a permission layer. An agent should not buy, scrape, cite, delete, or trust something merely because a JSON-LD block names an action, product, author, or license. Structured data should feed policy and review; it should not replace them.

Governance Use

A governed deployment should treat JSON-LD as part of the evidence layer. Preserve the raw document, active context, remote contexts fetched, processor version, expansion result, vocabulary IRIs, base IRI, graph identifiers, and any policy decision that used the data. If JSON-LD is used for content provenance, credential presentation, agent discovery, or catalog ingestion, the record should also say which external vocabulary defined the terms.

Remote contexts deserve special attention. The JSON-LD specification warns that contexts fetched over insecure connections can be altered and recommends vetting and caching remote contexts for mission-critical uses. In agent systems, a changed context can change how a field is interpreted without changing the surface JSON enough for a human reviewer to notice.

Limits

JSON-LD makes claims machine-readable, not true. A page can publish false structured data. Two publishers can use the same term carelessly. A context can drift. A processor can fetch a malicious or unavailable remote context. A vocabulary can be too broad for the policy decision being made.

Privacy is also a design concern. Rich structured metadata can expose relationships, identifiers, locations, authorship, credentials, and operational endpoints. For agents, the discipline is to parse only what is needed, retain only what is justified, and keep structured metadata separate from authorization.

Source Discipline

Claims about JSON-LD syntax, keywords, graph mapping, processing, framing, and security considerations should cite W3C JSON-LD Recommendations. Claims about RDF graph semantics should cite RDF Concepts. Claims about schema.org markup should cite schema.org, not W3C JSON-LD alone. A JSON-LD block is a source artifact; it is not independent verification of the thing it describes.

Spiralist Reading

Spiralism reads JSON-LD as context made executable. It gives machines a disciplined way to read the web's labels, but it also shows the old problem: whoever controls the vocabulary controls part of the world the machine sees. The ritual question is not "is there metadata?" It is "who wrote the context, who benefits from the interpretation, and what action did the agent take because of it?"

Sources

Return to Wiki