How can JSON-LD distinguish a typed date from plain text?

Definition: JSON-LD distinguishes a typed date from plain text with a value object. The @value entry carries the lexical form, while @type carries the IRI of the datatype, such as the XML Schema date datatype.

Key facts

• The JSON-LD 1.1 Recommendation defines a typed value by associating a value with an IRI that indicates its type.
• A JSON-LD value object must contain @value and may contain @type; the value of @type can be a term, an IRI, or a compact IRI, among the forms listed by the specification.
• When @value and @type occur in the same map, JSON-LD treats @type as a value type. A node type is a separate use of the same keyword.
• RDF 1.1 Concepts describes a literal with a lexical form and a datatype IRI. The datatype determines how the lexical form maps to a literal value.
• The RDF specification lists xsd:date as the datatype for dates in yyyy-mm-dd form, with or without a timezone.

What does the value object contain?

The object below follows the form used in the JSON-LD specification for an explicitly typed value. The string is the lexical form, and the full IRI identifies the datatype. The same structure can express a date-only value by using http://www.w3.org/2001/XMLSchema#date as @type and a date lexical form such as yyyy-mm-dd.

{
  "@value": "2010-05-29T14:17:39+02:00",
  "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
}

The JSON-LD Recommendation calls this a value object because it contains @value. Its grammar also allows @language, @direction, @index, and @context in a value object. @type cannot be combined with @language or @direction in the same value object.

How does the datatype separate a date from text?

RDF gives a literal both a lexical form and a datatype IRI. The lexical form is the character sequence, while the datatype supplies the mapping to a value. For the XML Schema date datatype, the RDF table identifies the value as a date with a yyyy-mm-dd lexical representation, with an optional timezone. A JSON string containing date-shaped characters therefore acquires date semantics through the datatype association.

Without that association, a value object has @value but no explicit @type. RDF describes simple literals as syntactic sugar for literals whose datatype IRI is http://www.w3.org/2001/XMLSchema#string. In a JSON-LD document, that makes the distinction visible in the object structure: the typed form has an @type entry, while the plain string form does not.

The lexical form still matters. RDF states that when a lexical form belongs to a datatype's lexical space, the literal value is produced by that datatype's lexical-to-value mapping. A lexical form outside that space is ill-typed, so adding a datatype IRI does not make every character sequence a valid date.

Can a context declare the type for a property?

Yes. JSON-LD can place @type in a term definition inside @context. The Recommendation gives this example for a date-time property:

{
  "@context": {
    "modified": {
      "@id": "http://purl.org/dc/terms/modified",
      "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
    }
  },
  "modified": "2010-05-29T14:17:39+02:00"
}

The property value is a JSON string in the compact document, but the context supplies its datatype. The specification says that the value is automatically interpreted as a dateTime value because of the information in the context. An explicit value object places the same information beside the value, which can make the datatype visible when the document is inspected without its context.

What should you check in JSON-LD?

First identify whether the value is a value object with @value. Then check whether @type resolves to the intended datatype IRI. For an XML Schema date, use the IRI ending in #date; for a date-time, use the IRI ending in #dateTime. Finally, check that the lexical form follows the datatype's lexical space. JSON-LD permits a term or compact IRI in @type, so inspection may require resolving the active context before comparing the expanded IRI.

Related terms

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

FAQ

Is @type describing the date or the object?

When @value and @type are in the same map, the JSON-LD Recommendation describes @type as a value type. When @type appears on a node object, it describes the node instead.

Is a date-shaped JSON string automatically a date?

The datatype association supplies the date meaning. A lexical form must belong to the datatype's lexical space for RDF to produce the corresponding literal value.

Can a value object carry both a datatype and a language?

No. JSON-LD permits @type or @language in the value object, and the specification forbids using both together.

Sources

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

---

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