What does @context do in a website's JSON-LD?

Definition: @context is the JSON-LD keyword that maps short terms to Internationalized Resource Identifiers (IRIs) and supplies processing rules for a JSON-LD document. Its @vocab entry sets the default vocabulary mapping for properties and type values that do not have another term definition.

Key facts

• The W3C JSON-LD 1.1 specification says that a context maps terms to IRIs, and that terms are case sensitive.
• A context can be embedded in the JSON-LD document or referenced by a URL. A relative context URL is resolved relative to the document that contains the reference.
• A term definition can be a string that maps a term to an IRI, or a map called an expanded term definition that adds rules such as @id and @type.
• @vocab supplies a common prefix for properties and values of @type when they do not match a term and are neither an IRI nor a compact IRI.
• The processing algorithms describe expansion as the transformation that removes context and makes the data structure more regular.

How does term expansion use @context?

During processing, a JSON-LD processor builds an active context. The W3C processing algorithms and API defines that active context as containing active term definitions, the current base IRI, and an optional vocabulary mapping. Each term definition contains an IRI mapping and can also contain type, language, container, direction, or context information.

For a simple mapping, the key name can therefore be expanded to the IRI assigned to it:

{
  "@context": {
    "name": "http://schema.org/name"
  },
  "name": "Manu Sporny"
}

The specification's expansion example produces a property named http://schema.org/name. A key such as status that does not expand to an IRI is ignored when the document is processed as Linked Data. The mapping applies outside the context definition itself.

What does the vocabulary mapping change?

@vocab gives the processor a default IRI prefix for bare properties and type values. In the W3C example below, Restaurant and name are expanded with http://example.com/vocab/:

{
  "@context": {
    "@vocab": "http://example.com/vocab/"
  },
  "@id": "http://example.org/places#BrewEats",
  "@type": "Restaurant",
  "name": "Brew Eats"
}

The expanded result uses http://example.com/vocab/Restaurant for the type and http://example.com/vocab/name for the property. A term definition takes priority when a key matches a defined term, while an explicit IRI or compact IRI already supplies its own expansion. The vocabulary mapping can be removed by setting "@vocab": null in a context.

What can an expanded term definition control?

An expanded term definition is useful when a website's JSON-LD needs more information than a term-to-IRI mapping. The W3C specification uses this form to map homepage to a property IRI and set "@type": "@id":

{
  "@context": {
    "homepage": {
      "@id": "http://schema.org/url",
      "@type": "@id"
    }
  },
  "homepage": "http://manu.sporny.org/"
}

The string value is then interpreted as an IRI and appears in expanded form under http://schema.org/url. Expanded term definitions also support index maps and rules for interpreting arrays as sets or lists. A context can be local to a node or value object, or loaded from a remote document whose top-level @context entry supplies the context definition.

How can you inspect it in a web page?

The JSON-LD specification states that JSON-LD content can be embedded in HTML in a script element whose type attribute is application/ld+json:

<script type="application/ld+json">
{
  "@context": "https://json-ld.org/contexts/person.jsonld",
  "@id": "http://dbpedia.org/resource/John_Lennon",
  "name": "John Lennon"
}
</script>

When a processor extracts that script element, the containing HTML document's Document Base URL establishes the default base IRI for the enclosed JSON-LD. Inspect the @context value first, then follow each term definition and the @vocab value before interpreting the expanded property and type IRIs.

Related terms

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

FAQ

Does @context contain the page's visible text?

No. It is a context definition that describes how JSON-LD keys and values are interpreted. The W3C specification says that a context definition is not itself data in a linked data graph.

Is @vocab the same as defining every property?

No. @vocab provides a default vocabulary mapping for eligible bare properties and type values. A named term can still have its own term definition, including an expanded definition with @id and @type.

Can a context be hosted separately from the page?

Yes. The specification permits a context to be referenced using a URL, including a relative URL. A processor retrieves the remote document and uses its top-level @context entry.

Sources

1. W3C, "JSON-LD 1.1: A JSON-based Serialization for Linked Data", 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