Most structured data is reviewed in the same flawed way: you scroll the JSON, find a key that looks wrong, and fix it. JSON-LD is not just nested JSON, though. It serializes a graph — a set of nodes linked by directed arcs — and the moment you read it as a tree you start losing the relationships that make it useful. This page walks through how to read a pasted document as a graph, what the JSON-LD 1.1 data model actually says about each piece, and which signals are real structural hints versus things a tool should never pretend to decide.

From JSON tree to directed graph

According to the W3C JSON-LD 1.1 Recommendation, a JSON-LD document serializes an RDF dataset: exactly one default graph and zero or more named graphs. A named graph pairs a graph name (an IRI or blank node identifier) with a graph, and the default graph has no name and may be empty. A graph itself is a labeled directed graph — nodes connected by directed arcs, where each arc label is an IRI or blank node identifier, called a property in JSON-LD syntax.

That framing changes how you read the text. A nested object under author is not "a child"; it is the value of an author arc, and it may be a node with its own outgoing arcs, a literal value, or a reference to a node defined elsewhere. The indentation is a serialization convenience. The arcs are the substance.

Every node is an IRI, a blank node, or a literal, and any node with an outgoing edge must be an IRI or a blank node. When you inspect a document interactively, the useful view is therefore selection-based: pick a node, see its incident arcs, then jump along an arc to the next node. If you are testing that workflow, the browser-local graph inspector is built for exactly this: paste a document, get a graph plus an inspector, and follow a relationship without re-reading the raw text.

Nodes, property arcs and the unconnected-node rule

A node object represents zero or more properties of a node. The grammar states that a graph must not contain unconnected nodes — nodes not joined by a property to any other node. The source's own note is precise about the scope: this effectively prohibits unnested, empty node objects and unnested node objects that contain only an @id. Unrelated nodes are allowed as long as properties are defined or the node is referenced from another node object. A diagnostics view should report an isolated node as a hint, not declare the file invalid JSON — the source says nothing of the kind.

A second grammar rule is easy to miss when you are eyeballing a document: in JSON-LD, keys inside an object must be unique. That is stricter than JSON generally. Duplicate keys are a legitimate structural flag. Merging of different node objects is a different matter, covered below.

Values, typed values and language strings

Not everything hanging off a property is a node. A JSON-LD value can be a typed value, a string (interpreted as typed with xsd:string), a number (xsd:double or xsd:integer depending on its form), a boolean, or a language-tagged string. The explicit value-object form carries its own constraints: a value object must contain @value and must not carry both @type and either @language or @direction, and direction is limited to ltr, rtl, or null.

Language tags must be non-empty and well-formed under BCP47; processors may normalize them to lowercase. If your tool upper-cases a language tag for display, be explicit that it is presentation, not data. This is the kind of detail that survives a careful review and gets silently mangled by a quick one.

Spread node objects and merged keys

Here is the relationship most often lost when reading JSON as a tree: the properties of a single node may be spread across different node objects in the document. When that happens, their keys are merged to create the properties of the resulting node. Seeing the same @id twice is therefore not automatically a bug. It may be a deliberate split, and a reader that treats the second occurrence as a duplicate error is misreading the data model.

This is why the inspector should anchor on identifiers rather than object positions. Selecting an identifier should surface every arc attached to it across the document, so you can see the merged result. The guide to how identifiers hold a graph together covers the identifier rules in more depth; briefly, a node object's @id must be an IRI reference or a compact IRI, and when a node object carries both @graph and @id, the @id becomes the graph name.

A hypothetical example. Imagine a pasted document where an Organization appears twice with the same @id: once with name and url, once with a partial address. A tree-reading reviewer sees two objects and wonders which one is "the" organization. A graph-reading reviewer sees one node with three properties, assembled from two node objects. The second reading is the one the data model describes.

Ordered lists versus unordered sets

Arrays in JSON-LD are unordered unless something says otherwise. @set is syntactic sugar; @list expresses an ordered sequence, interpreted as an RDF list. The schema.org data model page reinforces the distinction: multi-values are technically an unordered set by default, and while practically most parsers assume source order, that is not explicit and can be incorrect. For recipes, book authors, or steps, order can matter, so @list is the signal to look for.

When a graph view shows five values on a property, it should not imply ordinality. If present, a list marker can show that order is asserted; a plain array of values should display as a set. This is a display decision that prevents a real category of misreading.

Ignored data and the bounded supported subset

One of the most consequential statements in the data model section is that JSON-LD documents may contain data the data model cannot represent, and unless otherwise specified that data is ignored during processing. Properties not mapped to an IRI, blank node, or keyword are ignored. A visualizer that renders only what it understood will silently omit such content. That should be disclosed rather than hidden, because "not shown" and "not there" are different claims.

This is why a practical inspector declares a bounded, supported subset of JSON-LD and says so in the interface. Context processing, remote context loading, and expansion or compaction algorithms sit outside the structural data-model checks described here. A tool that renders a graph from a paste is performing structural diagnostics on the subset it supports; it is not running a full processor and should not imply that a rendered document was fully expanded.

Diagnostics are hints: what is deliberately not claimed

The schema.org data model page takes a pragmatic view of conformance. Types form a multiple-inheritance hierarchy, properties may have several domains and ranges, and it is not an error for an entity description to mix properties from several independent types — a thing can usefully be both a Book and a Product. The page also notes that checkers may warn about data that is ambiguous for consumers but are not obliged to treat unexpected structures as errors, and that type/property associations are closer to guidelines than formal rules.

Two consequences follow. First, mixing types is not a structural error, so a diagnostics view should not flag it as one. Second, structural checks do not constitute full validation, and they say nothing about whether a search engine will display a rich result. Schema.org says search engines will often accept flexible markup; that is not a guarantee for any specific document. A responsible tool keeps these categories separate: structural hints, advisory notes, and explicit non-claims.

Recall the earlier organization example. A structural view might flag an isolated node elsewhere in the document and a duplicate key in an unrelated block. According to the source's open-world stance, an unmentioned property means unknown, not false; per the conformance notes, an unexpected cross-type combination is not an error. The merged organization node itself should be presented as the working reading, since merging is what the data model describes. The tool's job is to make those relationships visible, then let you decide what to do.

What to do next

Take one real document you maintain and read it twice: once as nested JSON, noting every guess you make about which object "owns" a value, and once anchored on identifiers, following each arc to its target. Then ask whether your current process would have told you when a property was silently dropped for lack of a mapping, or whether it would have shown a clean render and let you assume completeness. If the answer is the latter, structural diagnostics with a disclosed bounded subset — the lab approach — is the safer starting point than treating a tidy graph as a clean bill of health. For the vocabulary side, keep the JSON-LD 1.1 Recommendation and the schema.org data model page open while you review; they will settle most "is this actually wrong?" questions faster than guessing, and they will tell you plainly when a strange-looking structure is simply allowed.