Expressions: Object fields and array values

This describes how to access object fields and array items.

Expressions may refer to a specific value within an object using a qualification expression. A qualification expression denotes the object to search a key in, and the key name. A qualification expression has two possible forms—dot qualification and subscript qualification. For each of these forms, an optional qualification variant is also available.

The dot qualification is an expression of the form:

object.qualification 

where object is an expression which results in a value of type object, and qualification is the name of a key contained in the object if the key is a valid identifier (i.e., starts with a letter and consists only of letters, numbers and underscore). For example, the expression: {"firstItem" : 3, "secondItem": 4}.secondItem will return the value 4.

The subscript qualification is an expression of the form:

object[qualification]

where object is an expression which results in a value of type object, and qualification is an expression that results in a value of type string (or a type that can be coerced to string)—identifying the key to look up in object. For example, the expression {"firstItem" : 3, "secondItem": 4}["first"+"Item"] returns the value 3.

A qualification expression that refers to a key that doesn't exist in the object in runtime will return a result of type null. A qualification expression that attempts to search a key in a value that is not an object will result in a runtime error.

The optional dot qualification is an expression of the form below. Its semantics are identical to the dot qualification expression except that an attempt to qualify a null value will return a result of type null.

object?.qualification 

The optional subscript qualification is an expression of the form below. Its semantics are identical to the subscript qualification expression except that an attempt to qualify a null value will return a result of type null.

object?[qualification]

Expressions may refer to a specific value within an array using an indexing expression. An indexing expression denotes the array to retrieve an item from, and the index of the item to retrieve.

Indexing expressions take the form:

array[qualification]

where array is an expression which results in a value of type array, and qualification is an expression that results in a value of type number (or a type that can be coerced to number)— identifying the index of the item to retrieve from array. The index of the first item in an array is 0. For example, the expression:[3, 4, 5][1+1] will return the value 5.

An indexing expression that refers to an index beyond the range that exists in the array in runtime will return a result of type null. An indexing expression that attempts to retrieve an item from a value that is not an array will result in a runtime error.

Like any other type of expression, field access and array indexing can be composed and chained to navigate through arbitrarily complex data structures. For example, the following expression:

rootObject.firstArray[2].anotherField

would lookup variable rootObject, and search for a key named firstArray within the returned object. In that array, the third element (with index 2) will be retrieved—expecting an object, and within that object the field anotherField will be retrieved.