I was inspired by a post from 3AP company’s blog Using HATEOAS with REST APIs to tackle and explore the JSON-LD format in this article, explaining the problem it solves, where it assists users, and where it does not. No unrealistic hype, or RDF related terminology - only factual information.

JSON is commonly used as the format for data transfer via the Internet. It is easily understood and is supported in many places. However, while JSON has been very successful, it has one key limitation:

JSON defines structure, but not meaning.

The Problem: JSON Without Meaning

A standard JSON document may contain information such as:

{
    "id": "123",
    "name": "alice",
    "status": "active"
}

While this data may be simple for humans to understand, there are still questions that need to be answered about what these identifiers mean for machine processing. For example:

What does it mean when we refer to an “id”?
What does it mean when we refer to “status”?
Is “name” referring to an individual (person), business (company), or some other entity type?

The only way to know what this data means is through documentation, developer expertise, and informal arrangements between teams. However, once the data is moved across organization or system boundaries, any assumptions made about how to interpret those values will fail.

What Does “JSON” Mean (and Not Mean)

The following points describe that:

JSON Is:

A method used to serialize data
A way to represent data hierarchically

JSON Is NOT:

A specification of a data model
A formalized method of signifying semantic meaning for the information
An organized or complete method of defining vocabulary that can be used to communicate across multiple systems using JSON

Field names are defined as strings. As previously stated, two organizations might utilize the same field names in their document structure, but have different meanings associated with them, and vice versa for documents with differing field names where the intended meaning is still the same.

This is where “JSON-LD” provides value.

What Is JSON-LD?

JSON-LD or “JSON for Linked Data,” is a W3C Standard for adding semantic meaning to your JSON document.

JSON-LD will allow you to do the following:

Define the meaning of each of your fields instead of simply naming them.
Link your data to common vocabularies.
Allow machines to understand the JSON beyond its structure.

Importantly, JSON-LD is also valid JSON; therefore, all existing systems will still be able to read and interpret it as normal without changing anything about the systems.

Core Concept: Context

The core concept behind JSON-LD is “context”.

For instance:

{
  "@context": "https://schema.org",
  "@type": "Person",
  "name": "Alice",
  "email": "alice@example.com"
}

The “@context” property provides the following pieces of information to the machine:

The vocabulary you are using.
What the “name” and “email” fields refer to.
That this object represents a “Person”.

As a result, your data is no longer simply a collection of strings but instead has a shared meaning that can be used by multiple systems.

Identity and Linking

JSON-LD treats “identity” as a first-class concept.

For example:

{
  "@id": "https://example.com/users/123", 
  "@type": "Person", 
  "name": "Alice"
}

This means:

This object has a globally unique identifier.
Any other system can reliably reference that object.
You can link between data from different systems.

This type of “linkability” is extremely important for “long-term” domains such as insurance, finance, or the public sector.

Here is another, more complex JSON-LD format sample. In this case, it’s a US-style health insurance plan HealthInsurancePlan

{
    "@context": "http://health-lifesci.schema.org/",
    "@type": "HealthInsurancePlan",
    "healthPlanId": "12345XX9876543",
    "name": "Sample Gold Health Plan",
    "benefitsSummaryUrl": "http://url/to/summary/benefits/coverage",
    "healthPlanMarketingUrl": "http://url/to/health/plan/information",
    "contactPoint": {
        "@type": "ContactPoint",
        "email": "email@address.com"
    },
    "healthPlanDrugTier": ["http://healthplan.schema.org/PreferredNetwork",
                                "http://healthplan.schema.org/NonPreferredNetwork"],
    "includesHealthPlanFormulary": [
        {
            "@type": "HealthPlanFormulary",
            "healthPlanDrugTier": "http://healthplan.schema.org/DrugTierGeneric",
            "offersPrescriptionByMail": true,
            "healthPlanCostSharing": [
                {
                    "@type": "HealthPlanCostSharingSpecification",
                    "healthPlanPharmacyCategory": "1-MONTH-IN-RETAIL",
                    "healthPlanCopay": {
                        "@type": "PriceSpecification",
                        "price": 20,
                        "priceCurrency": "USD"
                    },
                    "healthPlanCopayOption": "http://healthplan.schema.org/HealthPlanCopayAfterDeductable",
                    "healthPlanCoinsuranceRate": 0.1,
                    "healthPlanCoinsuranceOption": "http://healthplan.schema.org/HealthPlanCoinsuranceBeforeDeductable"
                },
                {
                    "@type": "HealthPlanCostSharingSpecification",
                    "healthPlanPharmacyCategory": "1-MONTH-IN-MAIL",
                        "healthPlanCopay": {
                        "@type": "PriceSpecification",
                        "price": 0,
                        "priceCurrency": "USD"
                    },
                    "healthPlanCopayOption": "http://healthplan.schema.org/HealthPlanCoPayNoCharge",
                    "healthPlanCoinsuranceRate": 0.2,
                    "healthPlanCoinsuranceOption": "http://healthplan.schema.org/HealthPlanCoinsuranceNone"
                }
            ]
            }, {
            "@type": "HealthPlanFormulary",
            "healthPlanDrugTier": "http://healthplan.schema.org/DrugTierBrand",
            "offersPrescriptionByMail": true,
            "healthPlanCostSharing": [
                {
                    "@type": "HealthPlanCostSharingSpecification",
                    "healthPlanPharmacyCategory": "1-MONTH-IN-RETAIL",
                    "healthPlanCopay": {
                        "@type": "PriceSpecification",
                        "price": 15,
                        "priceCurrency": "USD"
                    },
                    "healthPlanCopayOption": "http://healthplan.schema.org/HealthPlanCopayNone",
                    "healthPlanCoinsuranceRate": 0,
                    "healthPlanCoinsuranceOption": "http://healthplan.schema.org/HealthPlanCoinsuranceNone"
                },
                {
                    "@type": "HealthPlanCostSharingSpecification",
                    "healthPlanPharmacyCategory": "1-MONTH-IN-MAIL",
                    "healthPlanCopay": {
                        "@type": "PriceSpecification",
                        "price": 20,
                        "priceCurrency": "USD"
                    },
                    "healthPlanCopayOption": "http://healthplan.schema.org/HealthPlanCopayAfterDeductible",
                    "healthPlanCoinsuranceRate": 0.1,
                    "healthPlanCoinsuranceOption": "http://healthplan.schema.org/HealthPlanCoinsuranceBeforeDeductible"
                }
            ]
        }
    ]
}

JSON-LD Does Not Force You into a Graph Database (and Other Misunderstandings)

Many people think that using JSON-LD means you have to:

Store your data in an RDF store (any system that can store, manage, and query RDF data)
Use a triple store (a specific kind of RDF store that stores RDF explicitly as subject–predicate–object triples)
Use a semantic web infrastructure

That is not true.

JSON-LD can be:

Stored as plain JSON
Sent via a regular REST APIs
Gradually adopted over time

This means you can add semantic meaning without changing your persisted data model.

What Problem Does JSON-LD Solve?

JSON-LD is valuable when:

You want to share data between teams or organizations
You want the meaning of your data to remain consistent through documentation drift
Your systems will evolve at different paces
It is important that machines be able to interpret the meaning of the data (search, AI, automation…)

JSON-LD takes away the burden of human-generated documentation.

What JSON-LD Does Not Solve

JSON-LD does NOT:

Define how to implement a specific process (workflow)
Define what actions are allowed to be performed on it (through API calls)
Replace the need for a contract to be created between the two parties (i.e., between the system and the client)
Automate the version management of the data being sent

Instead, JSON-LD answers the question:

“What is this?”

Not:

“What can I do with it?”

And understanding this difference is essential.

When Is It Worth the Cost of Using JSON-LD?

It is important to know that using JSON-LD adds some complexity, such as:

The need to manage context
The need to govern vocabularies used
The extra cognitive load

Therefore, JSON-LD isn’t for every type of API. It makes sense to use JSON-LD when:

The domain you are working in will be stable for a long time
The integrations will outlive the team who created them
You want to ensure that the data can be reinterpreted in the future
You work in regulated or cross-border environments

Practical Engineering Principle

If you need to have the same basic understanding five years from now of what your data actually means, not just via a colleague or coworker, consider using JSON-LD.

If you don’t plan on keeping the data beyond a few days, if it is an internal and expendable asset, JSON-LD isn’t going to help you.

Why It’s Still Important in 2026

In 2026, data is accessed and processed by more and more systems, including

Automation tools
Analytics platforms
Artificial Intelligence Models
External Organizations

Systems are becoming more than just a means of exchanging data; they have actually begun to interpret the meaning of the data.

JSON-LD provides a way for engineers to encode intent and meaning into the data that they create, instead of simply providing a format for it.

Implementations / Libraries

JSON-LD is available in a number of popular programming languages. Below are listed some implementations of JSON-LD which are fully conforming to the official JSON-LD specifications.

JavaScript

TypeScript

jsonld-lint