How can JSON-LD attach a language to an individual text value?

Definition: A JSON-LD value object attaches metadata to one value. Put the text under @value and its BCP 47 language tag under @language; together they represent a language-tagged string.

Key facts

• The JSON-LD 1.1 specification defines a value object as a map that explicitly associates a type or a language with a value.
• The specification says that @language must use the lexical form described by BCP 47 or be null.
• The RDF 1.1 Concepts specification defines a language-tagged string as a literal with a lexical form and a non-empty language tag.
• The JSON-LD 1.1 API specification adds @language during expansion when a string has a language mapping or the active context has a default language.

What does the value object look like?

The JSON-LD syntax specification requires a value object to contain @value. It permits @language alongside that key, and the @value entry can contain a string, number, Boolean, or null. A language-tagged individual text value therefore has this shape:

{
  "@context": {
    "occupation": "https://example.org/occupation"
  },
  "occupation": {
    "@value": "Scientist",
    "@language": "en"
  }
}

Here, Scientist is the lexical value and en is its language tag. The value object describes the value attached to occupation; it does not create a separate node identifier. The value object rules also prohibit an object from carrying @type together with @language or @direction.

How does a context affect an individual value?

The W3C's String Internationalization section describes three relevant placements. A context can set a default language with "@language": "ja". A term definition can assign a language to values of one term. A value object can override the default for one string by putting the desired tag beside @value.

The default applies to string values that are not type coerced. A value object with "@language": null expresses a string without a language association, even when a default language is active. A scoped context can also set @language to null to clear the default for a subtree.

Language tags follow BCP 47. The RDF 1.1 definition of literals requires a non-empty, well-formed tag for a language-tagged string and permits processors to convert its lexical representation to lower case.

What happens during JSON-LD processing?

The JSON-LD API's expansion algorithm starts with a map containing @value. For a string, it selects the language mapping for the active property, or the active context's default language when the property has no mapping. When that language is present, the algorithm adds it to the expanded value object as @language.

The same algorithm rejects a value object that combines @language with a non-string @value, because only strings can be language-tagged. It also rejects extra entries outside the value-object keys and rejects @type when @language is present. These processing rules keep a language tag attached to a text value with a consistent data shape.

How can you check one value?

Inspect the object that represents the value and check four conditions against the JSON-LD value-object grammar:

• @value is present and contains the text.
• @language is a well-formed BCP 47 tag, or is null when the value has no language association.
• @type is absent when @language is present.
• The object has no other key that expands to an IRI or JSON-LD keyword.

If the source uses a compact string instead of an explicit value object, inspect the active context as well. The API can add @language from a term's language mapping or from the context's default language during expansion.

Related terms

• JSON-LD
• Structured data
• Schema.org @id
• HTML lang attribute

FAQ

Can @language be used with a number?

No. The JSON-LD API treats @language on a non-string @value as an invalid language-tagged value.

What does "@language": null do?

In a value object, it expresses a string without a language association. In a context, the W3C specification uses null to clear the default language for a subtree.

Sources

1. W3C, "JSON-LD 1.1", 16 July 2020
2. W3C, "JSON-LD 1.1 Processing Algorithms and API", 16 July 2020
3. W3C, "RDF 1.1 Concepts and Abstract Syntax", 25 February 2014

---

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