Traversal

The language exposed by Brine is flat but the data returned by the server is likely to include deeper data structures such as objects and collections. To allow selection within such structures a traversal language is embedded within some steps which will be indicated by the use of the TRAVERSAL placeholder.

The traversal language consists of a selected subset of JsonPath.

JsonPath Subset

A subset of JsonPath functionality will be officially supported that is believed to cover all needed use cases without requiring deep familiarity with JsonPath. This may lead to more numerous simple steps in place of fewer steps that use unsupported expressions. The simpler steps should result in specifications that are clearer: both in terms of being more readable and also having more precisely defined logic. Brine is designed to be ported to multiple runtimes and only the selected subset will be supported across those runtimes (which should facilitate porting to any runtimes for which a more complete JsonPath implementation does not exist). Any expressions not listed here will not be disallowed and will work if handled by the JsonPath implementation, but are not officially supported.

Cardinality

Each traversal expression will select all matching nodes which is therefore represented as a collection. Often, however, only a single node is expected or desired. Therefore the traversal expression will also be accompanied by a phrase which defines the expected cardinality, normally child and children. children will always return an array corresponding to all matched values while child will return the first matched value. When the targeted values is one or more arrays then children would return an array of such arrays whereas child would return the first such array. The distinction is therefore about the number of children matching the traversal path and not the type of such matched values: an single array should be retrieved with child, extracting an array of specific attribute collected from an array of objects should be done with children.

Expressions

.KEY

Access the child named KEY of the target node. The leading . can be omitted at the start of an expression.

.[INDEX]

Access the element of the array at index INDEX.

.[FROM:TO]

Access a slice of the array containing the elements at index FROM through TO (including both limits). TODO: Are both really included? A half-open interval seems more standard.