How can JSON-LD express an inverse relationship?

Definition: JSON-LD expresses an inverse relationship with the @reverse keyword. You can also define a reverse property in a context by mapping a term to an IRI with an @reverse entry, so the term presents the relationship in the opposite direction from the vocabulary property.

Key facts

• The JSON-LD 1.1 specification describes JSON-LD as a format for directed graphs, where each property points from a node to another node or value.
• In a node object, @reverse takes a map whose entries represent reverse properties. The values can be IRI references, compact IRIs, blank node identifiers, node objects, or arrays containing those forms.
• The same specification says that @reverse in an expanded term definition creates a reverse property. A term such as children can therefore expose the reverse of a vocabulary property named parent.
• An expanded term definition with @reverse cannot contain @id or @nest at the same time. Its optional @container value is limited to null, @set, or @index.
• The JSON-LD 1.1 Processing Algorithms and API represents this choice with a reverse property flag in each term definition and allows only set and index containers for reverse properties.

How does @reverse change the direction?

An ordinary property describes a relationship from the current node to its value. If the vocabulary provides parent, a child node can point to a parent with parent. A document centered on the parent can express the same graph in the opposite direction by putting parent inside an @reverse map. The specification describes this as serializing a directed graph in the reverse direction.

The node-level form looks like this. It keeps Homer as the current node while the parent relationship is attached in reverse to Bart and Lisa:

{
  "@id": "#homer",
  "http://example.com/vocab#name": "Homer",
  "@reverse": {
    "http://example.com/vocab#parent": [
      {"@id": "#bart", "http://example.com/vocab#name": "Bart"},
      {"@id": "#lisa", "http://example.com/vocab#name": "Lisa"}
    ]
  }
}

When expanded, the graph still contains parent edges from Bart and Lisa to Homer. The reverse syntax changes the JSON-LD shape used to express those edges; it does not introduce a second vocabulary property.

How can a context define a reverse property?

An expanded term definition describes how a term maps to its expanded identifier and how values for that term are handled. Put @reverse in that definition and assign it the IRI of the vocabulary property. The term then acts as a readable label for the inverse direction.

{
  "@context": {
    "name": "http://example.com/vocab#name",
    "children": {"@reverse": "http://example.com/vocab#parent"}
  },
  "@id": "#homer",
  "name": "Homer",
  "children": [
    {"@id": "#bart", "name": "Bart"},
    {"@id": "#lisa", "name": "Lisa"}
  ]
}

The W3C example uses this exact children to parent mapping. In the compacted form, the @reverse property disappears from the node because the context term carries the reverse direction. The processing API records that children is a reverse property and, during expansion, places its values in the @reverse map.

What restrictions apply to a reverse property?

The node-level @reverse value must be a map. Its entries represent reverse properties, and each entry value must be an IRI reference, compact IRI, blank node identifier, node object, or an array made from those kinds of values. A value object or list object is not a valid value for a reverse property during processing.

For a context term, the @reverse value must resolve to an IRI, blank node identifier, compact IRI, or term. The term definition cannot combine @reverse with @id or @nest. If it includes @container, use @set, @index, or null; the processing specification reports an invalid reverse property for other container values. This keeps the context declaration separate from ordinary identifier and nesting declarations.

How can you check the resulting data?

Inspect the context first. A declaration such as "children": {"@reverse": "...#parent"} is the signal that children is inverse to parent. Then inspect the node data for the term or for an explicit @reverse map. Expansion should reveal the vocabulary IRI under @reverse; the W3C example expands the children values to the parent relationship with Homer as their object.

Related terms

• JSON-LD
• Structured data
• Schema.org @id
• Microdata
• RDFa

FAQ

Is @reverse a vocabulary property?

No. It is a JSON-LD keyword that changes how a relationship is expressed. The vocabulary property remains the IRI inside the reverse map or the IRI assigned to the context term.

Can a reverse property use @id in the same term definition?

No. The JSON-LD 1.1 syntax rules say that a term definition with an @reverse entry cannot also contain @id or @nest.

Which containers can a reverse property use?

The processing API permits @set and @index containers for reverse properties. The syntax also permits null for the @container entry.

Sources

1. W3C, "JSON-LD 1.1", 16 July 2020
2. W3C, "JSON-LD 1.1 Processing Algorithms and API", 16 July 2020

---

Check how a page reads to answer engines. Open the GEO score analyzer