The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →A JSON-LD parser that looks only for fields such as name at the document root can miss valid data stored in @graph. JSON-LD 1.1 permits a root object containing @context and/or @graph, with the graph holding node objects that do not have to be connected. Use a JSON-LD processor when you need linked-data semantics; for a narrow extraction task, explicitly handle the document shapes your application accepts.
Why a root-only parser misses data
Many simple extractors parse JSON and then inspect the resulting object as if every useful property were at the top level. That works only when the document uses that particular arrangement. In JSON-LD, a type, name, or other property may belong to a node inside the root object’s @graph array instead.
As an Amazon Associate I earn from qualifying purchases.
The W3C JSON-LD 1.1 Recommendation allows a document to be a single node object, an array of node objects, or a root map containing only @context and/or @graph. The root graph form allows multiple nodes to share a context; those nodes need not form one connected graph. W3C JSON-LD 1.1
{
"@context": {
"name": "https://schema.org/name"
},
"@graph": [
{
"@id": "https://example.com/#site",
"name": "Example site"
},
{
"@id": "https://example.com/#article",
"name": "An article"
}
]
}In this example, the root has no name property. The values belong to node objects in @graph, so code that checks only document.name will not find them.
#1 Best Overall
JSON parsing is not JSON-LD processing
A JSON parser checks JSON syntax and builds ordinary data structures. It does not, by itself, interpret JSON-LD contexts, expand terms into their mapped identifiers, or apply the JSON-LD data model. As the W3C specification puts it, “A JSON-LD document is always a valid JSON document.” That relationship does not make a JSON syntax parser a JSON-LD processor. W3C JSON-LD 1.1
JSON-LD processing includes operations that normalize or reshape a document for different purposes:
- Expansion removes context and makes terms and values more explicit.
- Compaction applies a context to produce a tailored, more concise representation.
- Flattening gathers properties for nodes into a node-oriented structure. The result uses
@graphfor the default graph.
These operations are defined by the W3C JSON-LD API specification. A conforming processor implements expansion, compaction, and flattening according to the specified algorithms. That is a standards-level statement; it does not establish how any particular parser, application, or crawler behaves.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Choose the right implementation approach
| Approach | Best suited to | What it handles | Trade-off |
|---|---|---|---|
| Conforming JSON-LD processor | Applications that need JSON-LD semantics or must accept varied documents | Standardized processing operations, including expansion, compaction, and flattening | Requires using and integrating a JSON-LD implementation; behavior and supported versions depend on the chosen library |
| Constrained extractor | A controlled input source and a specific field-extraction need | Only the document forms and properties you deliberately support | Less implementation overhead, but it does not provide full JSON-LD processing and can miss unsupported shapes or context behavior |
The API specification defines processor behavior, not the capabilities of every individual library. Check the documentation for the processor and version you select rather than assuming all tools support the same features. W3C JSON-LD API
How to write a limited extractor safely
If your application only needs a few fields from a controlled set of documents, a small extractor can be appropriate. Define its accepted input shapes rather than treating a root-level lookup as a general JSON-LD parser.
- Parse the input as JSON. Handle invalid JSON separately; JSON-LD documents must also be valid JSON.
- Recognize the document form. Support a single node object, an array of node objects, and a root object with
@graphif those forms are in scope. - Inspect the nodes you have explicitly selected. For a root graph, iterate its node objects and extract only the fields your application needs.
- Define how you handle contexts and references. A simple field lookup does not necessarily resolve terms through
@contextor follow linked nodes. - Test the accepted shapes and reject or report the rest. Do not silently treat unrecognized structures as documents with no data.
This is deliberately limited handling, not a replacement for the JSON-LD processing model. Recursing through every possible nested arrangement or resolving references is a separate design decision; checking a root-level @graph alone does not implement full JSON-LD processing.
What this means for parsers and crawlers
The standard establishes which document forms and processing operations JSON-LD supports. It does not prove that a particular application or search crawler will discover a given node, process every supported form, or use its data in a specific way. Those claims require evidence about the implementation in question. Google Search Central’s general structured-data introduction is available at Google Search Central, but the standards facts above should not be mistaken for a claim about Google’s parser behavior.
Free tools Windows power users keep installed
One-click scans. No signup required.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
