Remapping

The following is a simple topic view specification that mirrors all topics below the path a to reference topics below the path b.

map ?a// to b/<path(1)>

A topic view with this specification will map a source topic at the path a/x/y/z to a reference topic at the path b/x/y/z.
The specification is simple, so the reference topic will exactly mirror the source topic.

Source selector

The source topic clause begins with the map keyword and is followed by a topic selector.

The following is an example of a source topic clause:

map ?foo/bar//

This matches the topics foo, bar and all of their descendants.

If any of the topic names contain spaces, wrap the selector in quotation marks.
For example, instead of map ?Results/Home_games//, use map ?Results/Home_games//.

Path mapping

The path of a reference topic is derived from the source topic according to the topic view path mapping. Both; the path of the source topic and its value can be used to determine the path of the reference topic.

A path mapping clause begins with the to keyword and is followed by a path mapping template.

A path mapping template is a topic path with embedded directives. Directives are evaluated when creating the topic reference and substituted into the topic path.

Directives are delimited by angle brackets (<, >) and consist of the name of the directive and a list of parameters.
The parameter list is comma-separated and surrounded by parentheses ((, )).

The following example adds a simple path mapping clause to the previous source topic clause:

map ?foo/bar// to /foo/bar/All/<path(3)>

The path mapping clause is the part after the to keyword.
path is a directive, with 3 as its only parameter.
The clause will make reference topics for all the topics under foo/bar at foo/bar/All in the topic tree.

There are three types of path mapping directive:

  • Source path directive

  • Source value directive

  • Expand value directive

Source path directives

A source path directive matches part of the source path, as defined by the source topic clause. This enables you to derive the path of the reference topics from all or part of the path of the source topics.

The syntax is <path(start, number)>:

  • start is the index of part of the source path (where the top level of the topic tree is indexed as 0)

  • number is the number of parts to include (optional; if not specified, the selection will extend to the end of the source path)

For example, if you have a source path a/b/c/d:

  • The source path directive <path(0, 2)> is mapped to the reference topic path a/b.
    The start parameter of 0 means start at index 0, which is the topic a, and the number parameter of 2 means to take two parts of the tree in total.

  • The source path directive <path(1)> is mapped to the reference topic path b/c/d.
    This time the start parameter is 1, which corresponds to the topic b.
    Because there is no number parameter, the match includes all the topics to the end of the path.

Source value directives

Source value directives enable you to derive the path of the reference topics from the values within a JSON source topic.

Source value directives are only applied to JSON source topics; if the path mapping contains a source value directive, non-JSON topics matching the source topic selector are ignored.

Source value directives use the keyword scalar and are parameterised by a single JSON pointer that extracts a scalar value from the source value.
A scalar value is a string, a number, true, false, or null; that is, anything other than an array or a object.

If the JSON pointer does not refer to a scalar value in the source value, no reference topic will be created.
This includes the cases where the JSON pointer refers to an array or an object), or when no part of the source value is selected.

Deriving the reference topic paths from part of the source topic value effectively creates a secondary index on the value.
For source value directives to work efficiently, the selected scalar values should be relatively stable.
If an update to the source topic changes the selected scalar value, the corresponding reference topic will be removed and a new reference topic will be created.

For example, given a source value of:

{
    "account" : "1234",
    "balance" : { "amount" : 12.57, "currency" : "USD" }
}

and a source value directive currency/<scalar(/balance/currency)>/account/<scalar(/account)>, the resulting reference topic path will be:

currency/USD/account/1234

If the extracted value is a string, it is copied literally to the reference topic path. A value that contains path separators (/) will create a reference topic path with more levels than the path mapping template.

An extracted value of null will be copied to the reference topic path as the string "null".

Expand value directives

Expand value directives enable you to create multiple reference topics from a single JSON source topic.

Expand value directives are only applied to JSON source topics. If the path mapping contains an expand value directive, non-JSON topics matching the source topic selector are ignored.

Expand value directives use the keyword expand and take one or two JSON pointers as parameters:

<expand(sourcePointer, pathPointer)>

The sourcePointer parameter is a JSON pointer used to specify an array or object to expand.

Every direct child of the indicated source value is expanded into a new reference topic.
If no pointer is specified, the value is expanded from the root.

The optional pathPointer parameter can be used to name the topic path.
A JSON pointer is used to specify a scalar value (that is, not an array or object) within the expanded value.
The value is used to derive the reference topic path.

For example, suppose this is the content of a JSON topic called allCars:

{
    "cars": [
        { "reg":"HY58XPA", "type":"Ford", "model":"Sierra" },
        { "reg":"PY59GCA", "type":"Fiat", "model":"Panda"},
        { "reg":"VA63ABC", "type":"Ford", "model":"Ka"}
    ]
}

The topic view specification map allCars to cars/<expand(/cars, /reg)> results in these reference topic paths:

cars/HY58XPA
cars/PY59GCA
cars/VA63ABC

The value of cars/HY58XPA is:

{
    "reg":   "HY58XPA",
    "type":  "Ford",
    "model": "Sierra"
}

If the second pointer is not specified or no scalar value is found for the pointer, the path fragment is taken from the key (if the child value is an object) or the index (if the child value is an array).

In the example above, if you use the topic view map allCars to cars/<expand(/cars)>, the topic path is taken from the index of the current array element resulting in topics:

cars/0
cars/1
cars/2

Expand directives can be nested (that is there can be more than one expand directive in a path mapping).
In this case, a second expand directive will use the value from the previous expand as its source (root) value and not the value of the source topic.
This also applies to scalar directives that follow an expand directive.

Suppose the previous array example is extended so that each car can have multiple drivers:

{
    "cars": [
        {
            "reg":     "HY58XPA",
            "drivers": [{"name" : "Bill"}, {"name" : "Fred"}]
        },
        {
            "reg":     "PY59GCA",
            "drivers": [{"name" : "Jane"}, {"name" : "Fred"}]
        },
        {
            "reg":     "VA63ABC",
            "drivers": [{"name" : "Tom"}, {"name" : "John"}]
		}
	]
}

This topic view uses nested expand directives to expand both levels of the array hierarchy, map allCars to cars/<expand(/cars, /reg)>/drivers/<expand(/drivers, /name)>, resulting in these reference topics:

cars/HY58XPA/drivers/Bill
cars/HY58XPA/drivers/Fred
cars/PY59GCA/drivers/Jane
cars/PY59GCA/drivers/Fred
cars/VA63ABC/drivers/Tom
cars/VA63ABC/drivers/John

The second expand directive takes the /drivers values from the previous expand, so the value of each topic is {"name" : "Bill"}, {"name" : "Fred"}, {"name" : "Jane"} and so on.

If expansion causes more than one mapping to the same topic path, only the first encountered will be created and updated.