In short. JSON-LD arrays are unordered by default, while @list expresses semantic ordering.
Definition: An ordinary JSON-LD array uses JSON array syntax, but its values form an unordered collection by default. Semantic order is expressed with a list object using
@list, or with a context term whose container is@list.
Key facts
- JSON-LD uses the same array representation as JSON, while the collection is unordered by default, according to the JSON-LD 1.1 specification.
- The specification defines a list as an ordered sequence of IRIs, blank nodes, and literals.
- A list object is a map with an
@listkey. It may also contain@index, with no other entries. - A term defined with
"@container": "@list"makes values of that property ordered. - The processing specification converts lists into RDF collections through its List to RDF Conversion algorithm, as described in JSON-LD 1.1 Processing Algorithms and API.
What does an ordinary array mean in JSON-LD?
JSON syntax presents array members in a sequence. JSON-LD gives that same syntax a data model meaning in which the collection is unordered by default. The position of a value in an ordinary property array therefore does not, by itself, state that the value comes before or after another value.
The distinction is between serialization and meaning. The JSON-LD specification says that order is preserved in regular JSON arrays, while regular JSON-LD arrays require an explicit definition for order. A property such as "keywords": ["alpha", "beta"] can therefore carry two visible positions without making alpha semantically precede beta.
How does @list express order?
JSON-LD represents an ordered collection with a list object. The object wraps the values under @list, which makes the ordering part of the JSON-LD representation:
{
"@context": {
"foaf": "http://xmlns.com/foaf/0.1/"
},
"foaf:nick": {
"@list": ["joe", "bob", "jaybee"]
}
}
The W3C example states that this use of the array is ordered and that order is maintained while processing the document. In the expanded form, the values remain inside an object with an @list entry. That wrapper is the signal that separates a JSON-LD list from an ordinary multi-valued property.
When every use of a property is a list, a context can move the signal into the term definition:
{
"@context": {
"nick": {
"@id": "http://xmlns.com/foaf/0.1/nick",
"@container": "@list"
}
},
"nick": ["joe", "bob", "jaybee"]
}
Here the visible value is an array, while the context says that the term represents a list. The syntax specification states that values using an @list container are represented as arrays even when there is one value or no value.
What happens when a processor expands the document?
The JSON-LD API expands a document and converts it to a node map before the RDF serialization algorithms process its nodes. A list object is handled by the Object to RDF Conversion algorithm, and the resulting list is transformed into an RDF collection. RDF represents that collection through linked rdf:first and rdf:rest statements ending at rdf:nil, so the sequence remains represented within RDF's set of statements.
The API also directs expansion to create a list object when a term's container mapping includes @list and the expanded value is not already a list object. Compaction can remove the visible wrapper when the active context includes @list; when it does not, the processor restores a list object with an @list entry. The semantic marker therefore travels through processing even when compact JSON shows an array.
Related terms
FAQ
Does the order in the source file prove semantic order?
No. The source file shows JSON array positions, while JSON-LD treats an ordinary array collection as unordered by default. Use @list or an @list container when sequence is part of the data.
When should a property use @list?
Use it when the property represents an ordered sequence. An explicit list object works for a single value, while a context with "@container": "@list" applies the list interpretation to every value of that term.
Is @set another way to preserve order?
No. The JSON-LD specification uses @set to describe unordered sets. It also describes @set in the document body as syntactic sugar that processing can optimize away.
Sources
Check how a page reads to answer engines. Open the GEO score analyzer