JSON-LD is the technology that tries to bridge the world of APIs and the world of linked data, and it represents one of the most intellectually ambitious and most underadopted ideas in the API space. JSON-LD — JSON for Linking Data — is a way to add semantic meaning to JSON payloads by connecting the data to shared vocabularies, so that a machine doesn’t just receive a field called “name” but understands that it refers to the same concept of “name” that everyone else uses. It’s JSON that carries its own meaning, linked to the broader web of structured data. I’ve been drawn to JSON-LD for years because it points at something genuinely important: APIs that don’t just move data but move data that means something, data that machines can understand semantically rather than just parse syntactically. The promise is enormous, and the adoption has been frustratingly limited — until, possibly, now.
The core idea is the marriage of JSON’s accessibility with linked data’s semantic power, and that combination is what makes JSON-LD special. The semantic web and linked data movements produced powerful ideas about machine-understandable meaning, but they were buried in formats — RDF, SPARQL, complex ontologies — that most developers found impenetrable. JSON-LD’s breakthrough was making linked data accessible by expressing it in JSON, the format developers already knew and loved. Markus Lanthaler, whom I got to know through the hypermedia community, did foundational work here, including on Hydra, which builds hypermedia controls on top of JSON-LD. The genius of JSON-LD is that you can adopt it incrementally: your JSON looks like normal JSON, but with a “@context” that links your fields to shared vocabularies, your data becomes semantically meaningful without forcing developers to abandon the formats and tools they already use. It’s linked data that doesn’t require you to learn the semantic web.
Schema.org is where JSON-LD’s value becomes most concrete, and it’s the connection I’ve returned to most often. Schema.org is a shared vocabulary for describing common things — people, places, events, products, organizations — and JSON-LD is one of the primary ways to express Schema.org data. I generated OpenAPI definitions for the entire Schema.org vocabulary precisely because Schema.org represents what a data commons looks like: a rich, shared set of definitions that lets everyone describe common things the same way. When your API speaks Schema.org through JSON-LD, your data becomes interoperable with everyone else’s data about the same kinds of things. I wrote about Schema.org’s relationship to API discovery, and about why Schema.org doesn’t see more adoption across the API landscape — because the value of speaking a shared semantic vocabulary is real but diffuse, the classic commons problem where the benefit is collective and the individual incentive to participate is weak.
The discovery dimension is where JSON-LD intersects with my deepest interests, and I’ve explored it directly. I wrote in 2019 about embedding JSON-LD to power API discovery — using JSON-LD’s semantic markup to make APIs discoverable and understandable to machines. This connects JSON-LD to the discovery problem I’ve chased for years: if APIs describe themselves semantically, using shared vocabularies, then machines can discover and understand them based on meaning rather than just matching strings. The government services schemas with JSON-LD work I did in 2013, and the Digital Public Library of America’s use of APIs and JSON-LD to connect historical records, both showed JSON-LD doing real work — letting diverse data sources describe themselves in a common semantic framework so they could be discovered, connected, and understood together. JSON-LD is, in a sense, the semantic layer that discovery has always needed.
The adoption frustration is real and worth naming honestly, because JSON-LD’s story has been one of unrealized potential. For all its elegance and all its promise, JSON-LD never achieved broad adoption across the API landscape. I asked directly in 2019 why Schema.org and the semantic approach don’t see more adoption, and the answer is the same one that explains hypermedia’s limited uptake: cognitive load and diffuse benefit. Adding JSON-LD context to your API is extra work, the payoff is mostly collective rather than individual, and most developers and organizations chose the simpler path of plain JSON without semantic markup. The semantic web’s long history of being perpetually almost-relevant haunts JSON-LD — it’s clearly a good idea that the market has consistently declined to fully embrace. The selfish-standardization framing I used in 2025, about using JSON-LD for job postings, captures the one reliable adoption driver: people adopt JSON-LD when there’s a direct, selfish benefit (like SEO and Google’s rich results), not for the collective good of a semantic web.
The fascinating turn, and where I’m genuinely hopeful, is that AI and agents may finally give JSON-LD its moment, just as they may for hypermedia. I wrote in 2025 that where people see AI agents, I see API discovery, semantics, hypermedia, and workflows — and JSON-LD’s semantic markup is exactly what AI agents need to understand APIs and data at the level of meaning rather than syntax. The CarAPI’s use of HAL and JSON-LD hypermedia, which I covered in 2025, points at how semantic, self-describing APIs serve machine consumers. For fifteen years JSON-LD was a beautiful answer to a question most developers weren’t asking, because human developers could supply the semantic understanding themselves by reading documentation. But an AI agent navigating APIs at scale needs the data to carry its own meaning, and JSON-LD provides exactly that. The semantic understanding that JSON-LD encodes — the linking of data to shared vocabularies so meaning is explicit and machine-processable — is precisely what agents need to act reliably across diverse APIs. JSON-LD may have been early rather than wrong, a technology built for a world of machine consumers that is only now arriving. If that’s true, then all the semantic-web work that looked like a dead end may turn out to have been laying the foundation for the agentic era, and JSON-LD’s long-delayed moment may finally be at hand.
References
- Government Services Schemas With JSON-LD
- Getting To Know Markus Lanthaler For The API Craft 2014 Detroit Hypermedia Panel
- Connecting Our History At The Digital Public Library Of America Using APIs And JSON-LD
- Thinking About Schema.org’s Relationship To API Discovery
- REST, Linked Data, Hypermedia, GraphQL, And gRPC
- OpenAPI Definitions For Entire Schema.org Vocabulary (Do Not Reinvent Wheel)
- Why Schema.org Does Not See More Adoption Across The API Landscape
- Embedding JSON-LD To Power API Discovery
- You See AI Agents, But API Evangelist Just Sees API Discovery, Semantics, Hypermedia, And Workflows
- HAL And JSON-LD Hypermedia In Use By The CarAPI
- Selfish Standardization Using JSON-LD For Job Postings
