JSON format for conditions rules and queries

One unified JSON format that is used for conditions in dynamic groups, rules in rules-based service models, and in the query builder that combines a condition with a tabular representation of the data.

Expression types

Expression type

Syntax

Literal string

"simple JSON string"

Literal number

123

Literal array

[1, 2, "foo"]

Datetime

{ "type": "datetime", "value": "ISO-8601 format datetime" }

Direct attribute of node

{ "type": "attr", "name": "attribute name" }

Attribute of related node

{ "type": "attr", "ref": "label of other block", "name": "attribute name" }

Count of related nodes

{ "type": "count", "ref": "label of other block" }

Combinations

{ "type": "operator", "items": [expression...]}

Where operator is one of:

all	true if all the items evaluate to true
any	true if any of the items evaluates to true

Binary expression

{ "type": "operator", "left": expression, "right": expression }

Operator is one of:

~~and~~	~~logical and~~ (use all defined above)
or	~~logical or~~ (use any defined above)
=	equal
>	greater than
>=	greater than or equal
<	less than
<=	less than or equal
matches	Python regular expression match
subword	word / phrase match
substring	case insensitive substring match
in	exact match of a member of a list
+	arithmetic addition / string concatenation
-	arithmetic subtraction
*	arithmetic multiplication
/	arithmetic division
subscript	left.right. right may be a literal array to represent a multi-level lookup, for example, ["a","b","c"] means left.a.b.c

Unary expression

{ "type": "operator", "item": expression }

Operator is one of:

not	logical not
-	unary minus (distinguished from binary subtract because it has an "item" not a "left" and "right")
defined	if expression is an attribute, true if the attribute exists on the node; with other expression types, true if the expression value is not None / null

Function

{ "type": "function", "name": "function_name", "args": [ expression, ... ] }

Functions are the same as the search functions, listed at query language functions.

Plus, a small number of additions to match CAM named value transformations: Using-and-manipulating-named-values.

Table

{ "type": "table", "item": expression, "default": "value", "table": { "key": "value", ... } }

String look-up table. Looks up item in table; if the value is not found, returns default.

Named value

{ "type": "named_value", "name": "value_name" }

References a name defined in another block.

Parameter

{ "type": "parameter", "name": "param_name", "param_type": "param_type", "description": "parameter description for UI"}

A parameter that the user must provide. param_type is one of

string
integer
float
boolean
datetime
list:type (giving one of the types above)
attr (a parameterised attribute name – see below)
attr:prefix (attribute name where the attribute must have a specific prefix)

When creating a populated version of the condition with the parameter filled in, the parameter becomes a literal value. In the simple case that the parameter was the right-hand-side of a binary expression, a UI could permit the user to choose a different compatible operator. For example if the condition is that the name attribute is equal to the parameter value, the user could change it to a condition where the name matches a regular expression. This is valid for:

=
>
>=
<
<=
matches
subword
substring

Attribute parameters (param_type = "attr") are slightly different. They allow the user to choose an attribute name, usually on the left-hand-side of an expression. If a prefix is specified, the attribute name must be prefixed with that string. This is used for tags where the user may choose a tag name, with a param_type = "attr:tag_". When providing the value for an attribute parameter, the caller provides just the chosen attribute name as a string, for example, "tag_location", not a full expression with a type of attr.

Node condition object

Node conditions in the JSON have the following fields

Field	Required	Description
type	Yes	Must be "node"
label	No	Label used to refer to this graph element in relationships and other references. Not required if there are no references to the node. The label must be a valid attribute identifier. It must start with a letter and contain letters, numbers and underscores. [a-zA-Z][a-zA-Z0-9_]*
kind	Yes	Node kind that it matches. May be a single string, an array of strings, or the single empty string "" for all node kinds
partition	No	Partition name to search within. If not specified, searches all default-searchable partitions. Only takes effect for top-level nodes that are searched for, not for relationships that are followed.
required	No	true or false, to indicate whether a matching node must be found for the whole graph to be considered a match. If not specified, defaults to true
in_model	No	When used as part of a service model definition, true or false to indicate whether the matches nodes are considered part of the model or not. If not specified, defaults to true
condition	No	A single condition in the expression format described above. Only nodes matching the condition are chosen. If not specified, matches all nodes of the specified kinds
show	No	Ordered expressions used when generating a search show clause in tabular or tree format. Expressions may have an extra "heading" attribute that determines the heading / as expression for the show clause.
order_by	No	Expression used to order results when evaluating a search
name	No	Name of the graph element, used as the name attribute in Functional Components in rule-based service models. If not set, FunctionalComponents are not created
description	No	Description of the element, stored on Functional Components when created
notes	No	Text notes (in RE-structured text format?)
named_values	No	In rule-based service models, defines names that can be referenced elsewhere. Contains an object mapping named value name to an expression object. The expression object may have an additional boolean member "identity", which if true means that the service instance identity comes from that named value. Only one named value in any connected condition tree may be the identity.

Relationship condition object

All the same fields as Node conditions, plus:

Field	Required	Description
type	Yes	Must be "rel"
kind	Yes	Relationship kind, or empty string to indicate a wildcard
roles	Yes	Array of two objects each with two required members: "role" contains the role name, or empty string to match wildcard "ref" must be a label defined in a node condition (or relationship condition) May also contain either or both of: "min": Minimum number of matching relationships that must be present for the graph condition to match. If not specified, default is 1 (or 0 if max is 0) "max": Maximum number of matching relationships. If not specified, default is unlimited.

Trees, graphs and cycles in relationships

Conditions are evaluated as trees. The condition specification can be a graph, but it is always evaluated as a tree that follows a breadth-first traversal from a chosen starting condition. For example, if a condition is like this:

Then if starting from condition A, it is equivalent to a tree:

whereas if starting from condition D, it is equivalent to this tree: