JSON Query Format

The query format is still very much in flux as I work through different use cases. Please check back here regularly -Thom.

The Query is specified as part of a device spec sent in a buffer to N: SIO Command $81 - Query JSON. e.g.

Nx:title

Would retrieve the "title" object from the JSON stream pointed to by Nx:.

The top level element

Specifying a blank query string:

Nx:

Indicates that the top level element should be selected to be returned.

Asking for specific element

If the element pointed by the query is not an object or array, the specific element is returned on the very next N: SIO Command 'R' - Read command as a string ending in an ATASCII EOL, e.g. Given an example bit of JSON from https://jsonplaceholder.typicode.com/todos/1:

{
  "userId": 1,
  "id": 1,
  "title": "delectus aut autem",
  "completed": false
}

The query string

N1:TITLE

Would return the contents of that string object:

delectus aut autem

on the next read.

Element types

Containers (Objects and Arrays)

JSON has a number of element types. Two of these element types, Objects and Arrays, are containers. While Objects can contain any element type (including arrays), arrays must by definition contain only a single element type. Each element in the container is seperated by a comma, and reflexively each container type can contain the other.

Array

Arrays are groups of a single element type, and are contained within brackets []

[
    "String 1",
    "String 2",
    "String 3"
]

When an array is selected, each element of the array is returned sequentially on each read.

Object

Objects allow for different types of information to be grouped together, and are contained within braces {}

{
        "key1":"value1",
        "num2":1234,
        "bool3":true,
        "array4": [0, 1, 2, 3, 4],
        "object5": { "child1":"val1", "child2":"val2"}
}

String

Strings are quoted alphanumeric elements:

"title":"Some Title"

Number

Numeric values are represented internally as double precision floating point elements, and are returned by the JSON parser as a string. This allows languages like ATARI BASIC to automatically adapt the input to either a string or numeric variable.

"views":1234

Boolean

Boolean values 'true' and 'false' are returned as strings TRUE or FALSE respectively.

"done":true

Null value

JSON specifies a null value, meaning the key does not have a defined value. This is returned as the string NULL.

"optionalValue":null

Element Depth Seperator "/"

Tenatively, the forward slash character is being used to indicate depth of an object or array element. e.g.

Nx:test1/test2/test3

could select something from a JSON structure similar to:

{
        "test1": {
                "test2": {
                        "test3": "Some value"
                }
        }
}

and the subsequent N: SIO Command 'R' - Read would return the value:

Some value

terminated by an ATASCII EOL.

Traversal Mode

If the element pointed to by the query string is a container, then the elements of that container are returned in successive N: SIO Command 'R' - Read commands. Reads beyond the last element will return an ERROR, with the subsequent status indicating than an ERROR 136 (EOF) has occurred.

Traversing Objects

If the element pointed to is an object, then each element contained within the object will be returned as a pair of reads (TODO: DEAL WITH CONSISTENTLY REPRESENTING OBJECT RECURSION!), with the first read being a string containing key, and the second read containing the value. The next read will either return the next element, or an ERROR, with a subsequent status indicating that an ERROR 136 (EOF) has occurred.

Traversing Arrays

In contrast to objects, arrays can only hold elements of the same type, therefore, each element in the array can be read with a single N: SIO Command 'R' - Read command for each element.