Structure path

Structure path is similar to a JSON path but designed to work better for our use case. It is primarily used for selecting a subtree of an object. In some cases it is extended to provide the possibility of targeting a write subtree.

Syntax

An empty path always means the root of the object. Navigation is only available inwards and always starts from the root.

Read syntax:

To select a field you have to name it: fieldName.

To select a field object’s field you have to separate their names by a dot: rootFieldName.childFieldName. This is used for inwards navigation.

To select an array element you have to index it (starting from 0): arrayFieldName[0]. Using arrayFieldName[7].childFieldNode also works.

Write syntax:

Read syntax is included as the selected subtree will be modified.

Targeting the root object (using empty path) will modify the whole object just like any other subtree.

Append to an array: pathToArray[+]:

In case the write value is another array it will append its elements to the target array’s end.

Value

Target path

Read path

Read value after write

["web", "js"]

tags[+]

tags

["android", "ios", "web", "js"]

In case the write value is not an array that value will be added to the target array’s end.

Value

Target path

Read path

Read value after write

"web"

tags[+]

tags

["android", "ios", "web"]

{"type":"none"}

tags[+]

tags

["android", "ios", "web", {"type":"none"}]

There are more options coming for better array operations.

Behavior

When reading a value from a subtree, the whole subtree is returned. If the selected path does not exist in the source object, null is returned which means not existing value in StructureObject.

When writing a value to a subtree the target subtree is manipulated. If the target path does not exist, it will be created. This will add or replace values along the target path initialized to be empty except the target path.

Note

When a target array is not big enough or does not exist it will be extended or created and the other indexes will be filled by null.

Samples

Let’s assume that we are working on an object like the following JSON.

{
    "key": "common_ok",
    "languages": {
        "en": "OK",
        "hu": "Rendben"
    },
    "tags": [
        "android",
        "ios"
    ],
    "meta": [
        {
            "key": "MetaKey"
        }
    ]
}

Read

key: common_ok (String)
languages: {"en": "OK","hu":"Rendben"} (Object)
languages[0]: ERROR
languages.en: OK (String)
tags: ["android", "ios"] (Array)
tags[0]: android (String)
comment: null (Not existing)
comment.en: null (Not existing)

Write

Value	Target path	Read path	Read value after write
`"common_accept"`	`key`	`key`	`common_accept`
`"My string"`	`languages`	`languages`	`My string`
`"Annehmen"`	`languages.de`	`languages`	`{"en": "OK","hu":"Rendben","de": "Annehmen"}`
`"My comment"`	`comment`	`comment`	`My comment`
`"My comment"`	`comment.en`	`comment`	`{"en":"My comment"}`
`"web"`	`tags[3]`	`tags`	`["android", "ios", null, "web"]`
`"web"`	`tags[0]`	`tags`	`["web", "ios"]`
`"web"`	`tags[+]`	`tags`	`["android", "ios", "web"]`
`{"type":"none"}`	`tags[+]`	`tags`	`["android", "ios", "web", {"type":"none"}]`
`["web", "js"]`	`tags[+]`	`tags`	`["android", "ios", "web", "js"]`

Write behaviour with merge

When you use Structure Path for write usually you can choose a write behavior. It is override by default but you can choose merge instead. In this case the behavior is slightly different.
In case of single values the behavior is the same as the override. Merge can be understood like multiple overrides but for each value in nested paths.
Let’s see a few examples:

Value	Target path	Read path	Read value after write
`"common_accept"`	`key`	`key`	`common_accept`
`"My string"`	`languages`	`languages`	`My string`
`"Annehmen"`	`languages.de`	`languages`	`{"en": "OK","hu":"Rendben","de": "Annehmen"}`
`{"de": "Annehmen"}`	`languages`	`languages`	`{"en": "OK","hu":"Rendben","de": "Annehmen"}`
`{"de":"OK","en":"YES"}`	`languages`	`languages`	`{"en": "YES","hu":"Rendben","de": "OK"}`
`{"value":"AAA", "t": 1}`	`meta[0]`	`meta[0]`	`{"key": "MetaKey","value":"AAA", "t": 1}`

Warning

Array append is not available with merge!