How are relative identifiers resolved in JSON-LD?

Definition: In JSON-LD, a relative IRI reference is an identifier written without a complete absolute form. The JSON-LD 1.1 specification resolves it against a base IRI, which can come from the document location or from an @base setting in a context.

Key facts

• JSON-LD resolves relative IRIs against the document base using the base-URI procedure in RFC 3986, and a context can set that base with @base.
• If a document was retrieved from http://example.com/document.jsonld, the specification resolves its relative IRI references against that IRI.
• An empty @id resolves to the document base. Moving the document to another location changes the resulting IRI.
• For JSON-LD in an HTML script element, the containing document's Document Base URL establishes the default base IRI.

How is the document base chosen?

RFC 3986 defines relative resolution as converting a URI reference that may be relative into the target components for a given base URI. The parser establishes a base before it parses references that may be relative, and the base must use an absolute URI form.

The RFC gives four base sources in precedence order: a base embedded in the content, the base of an encapsulating entity, the URI used to retrieve the representation, and an application-defined default. For a representation that has no earlier base and was retrieved with a URI, that retrieval URI is the base. If a redirect occurred, the last URI used to retrieve the representation is the base.

JSON-LD applies this rule to a document location. Its example retrieves a document at http://example.com/document.jsonld and uses an empty @id, which resolves to that document base.

What does @base change?

The JSON-LD specification allows its context to overwrite the document base with an explicit @base value. It demonstrates this with an empty @id and a context base:

{
  "@context": {
    "@base": "http://example.com/document.jsonld",
    "label": "http://www.w3.org/2000/01/rdf-schema#label"
  },
  "@id": "",
  "label": "Just a simple document"
}

The expanded identifier in that example is http://example.com/document.jsonld. Setting @base to null prevents relative IRI references from being expanded to IRIs. The specification also states that @base is ignored when it is used in an external context.

How does an HTML document affect the base?

When JSON-LD is processed inside an HTML script element, the containing HTML document's Document Base URL establishes the default base IRI. The JSON-LD specification illustrates this with an HTML base element and relative JSON-LD identifiers:

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

The example expands John_Lennon to http://dbpedia.org/resource/John_Lennon and Cynthia_Lennon to http://dbpedia.org/resource/Cynthia_Lennon. The same specification says that it does not require specific behavior for dynamic changes to HTML base URLs, and recommends using absolute IRIs or explicitly defining the base as described in its Base IRI section.

How can the result be checked?

Record the URL that supplied the document, the final retrieval URL after any redirect, and every in-document context that contains @base. For a JSON-LD script in HTML, record the document's base element and Document Base URL. Compare the expanded identifiers with the RFC 3986 resolution procedure and with the JSON-LD specification's empty @id and HTML examples.

Related terms

• JSON-LD
• Schema.org @id
• Canonical URL
• URL parameters

FAQ

Does the page URL always become the base IRI?

RFC 3986 uses the retrieval URI when no embedded or encapsulating base has precedence. A JSON-LD context can set @base, and an HTML document can establish a base for an embedded JSON-LD script.

What happens when @base is null?

The JSON-LD specification says that setting @base to null prevents relative IRI references from being expanded to IRIs.

Does moving a JSON-LD document change an empty @id?

The specification's example says that an empty @id resolves to the document base and that moving the document to a different location changes the IRI.

Sources

1. W3C, "JSON-LD 1.1", 16 July 2020
2. IETF, "Uniform Resource Identifier (URI): Generic Syntax", January 2005

---

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