Condition Expressions

Conditions are used in two places in the schema to express boolean logic:

  • Field requiredness: field.condition — the field is required when the condition is true.
  • View discriminators: fieldSetWithContext.condition — identifies the context this view applies to (required).

Instead of building a proprietary condition syntax, FinSpec uses the well-known Disjunctive Normal Form (DNF) structure:

A condition is expressed as an or array of and groups, each of which is an array of leaf conditionNode tests. The condition is true if any or group is true; a group is true if all of its leaf tests are true.

json
"condition": {
  "or": [
    {
      "and": [
        {
          "tag": "40",
          "operator": "equals",
          "value": "2",
          "text": "OrdType equals 2 (Limit)"
        }
      ]
    },
    {
      "and": [
        {
          "tag": "40",
          "operator":  "equals",
          "value": "4",
          "text": "OrdType equals 4 (StopLimit)"
        }
      ]
    }
  ]
}

This expression should be understood to mean: “OrdType = 2 (Limit) OR OrdType = 4 (StopLimit)”.

Note that the operator determines how tag is compared, and value holds a fixed value for the comparison.

FinSpec also supports field-to-field comparisons, using the _field suffixed operators. When using this form, the operators should compare tag against the runtime value of a $-prefixed reference to the other field (e.g. "$44" to reference the field with wire id 44).

The or_missing operator lets a leaf test pass when tag is absent from the message, rather than the default behaviour of implicitly requiring tag to be present.

Table: Population of value and reference attributes based on operator
operator value reference
present omit omit
not_present omit omit
equals required omit
not_equals required omit
one_of required omit
not_in required omit
starts_with required omit
ends_with required omit
contains required omit
regex required omit
not_regex required omit
gt required omit
gte required omit
lt required omit
lte required omit
equals_field omit required
not_equals_field omit required
gt_field omit required
gte_field omit required
lt_field omit required
lte_field omit required

Human-Readable Condition

We recommend programmatically populating the human-readable text field in each conditionNode leaf, as this aids presentation. These individual text values can then be rolled up to populate an overall human-readable description in conditionHuman.

FAQs

What happens if no or group evaluates to true? The condition is false. For field.condition, that means the field isn’t required in the current context. For fieldSetWithContext.condition, it means the view doesn’t apply to that message instance.

Can I compare two fields to each other, rather than a field to a fixed value? Yes — use one of the _field-suffixed operators (e.g. equals_field) with reference set to a $-prefixed tag, such as "$44", as described above.

Do I have to populate text and conditionHuman myself? No, but we strongly recommend it. Without them, a human reading the raw condition tree has to reverse-engineer the logic by hand; with them, tooling and documentation can show a plain-English explanation alongside the machine-readable rule.