JSON-LD and Linked Product Data

A passport is read by systems built by organisations that have never spoken to the organisation that wrote it. That single fact is why the data format question is not merely a matter of engineering preference.

JSON-LD exists to address exactly this, and understanding what it adds over plain JSON explains why the standards in this space keep converging on it.

The problem with plain JSON

JSON conveys structure and values perfectly well. What it does not convey is meaning, and meaning is exactly what a stranger’s system needs.

A field named weight carries a number. Whether that is net weight, gross weight, shipping weight or weight excluding packaging is knowledge held by the developer who wrote it, communicated through documentation if at all.

What JSON-LD adds

JSON-LD keeps JSON syntax and adds a context that maps each field name onto a definition identified by a URI. The field is still called weight in the document; the context says which weight it is.

The third row is the whole point. Two manufacturers using different field names for the same concept produce documents that a consuming system can reconcile automatically, provided both map to the same definition.

Why passports inherit it anyway

Even a team that would not choose JSON-LD on its merits is likely to end up using it, because the surrounding standards already do.

• W3C verifiable credentials use JSON-LD for their data model, and passports carry credentials.
• Schema.org vocabularies are expressed this way, and they govern how search engines read product pages.
• GS1 vocabularies provide linked data definitions for product concepts.
• CIRPASS work on passport data models builds on the same foundations.

The second point has an immediate commercial dimension that is easy to overlook. Structured product data expressed this way is what allows search engines and AI systems to extract and cite product information accurately, which affects whether your products appear correctly in answers.

The context is the commitment

A JSON-LD document points at a context document, usually by URL, and that pointer is a long-lived dependency worth treating carefully.

The practical mitigations are to host contexts on stable infrastructure separate from marketing sites, to version them so an old document keeps referring to the definitions it was written against, and to expect consumers to cache them rather than fetch on every read.

Where it costs you something

It would be unbalanced to present this as free. JSON-LD carries real costs and they fall on the producer more than the consumer.

Documents are more verbose, processing requires a library rather than a plain parser, and the expansion and compaction algorithms have edge cases that surprise people. Debugging a context problem is considerably less pleasant than debugging a schema mismatch.

There is also a genuine risk of over-engineering. A team can spend months on ontology design for a passport that would have been perfectly serviceable with a small vocabulary and a published mapping, and the elaborate version is not more useful to the recycler who has to read it.

A proportionate approach

The position that holds up is to use JSON-LD where interoperability with strangers is the requirement and not to build a semantic web where one is not needed.

Reuse existing vocabularies rather than defining your own wherever one exists, which is more often than teams assume. Define new terms only for concepts genuinely specific to your products, and publish those definitions where a consumer can reach them.

Serve plain JSON as well for consumers who want it, since content negotiation makes that straightforward and there is no reason to force a partner integration through linked data processing it does not need.

How to tell if you got it right

The test is not whether the document validates. It is whether somebody who has never contacted you can process it correctly on their first attempt.

That is worth testing literally, by giving a passport document to a developer outside your organisation with no explanation and observing what they get wrong. The fields they misinterpret are the ones where the context is doing less work than you assumed, and no amount of internal review surfaces them as reliably.