---
seo:
    title: "Condition Expressions"
    description: "Condition expressions in FinSpec define the context-specific logic for field conditionality and view context within a specification."
llm_context: "Reference for the machine-readable condition syntax that allows machines to understand conditionality. The condition object is used (a) to express when a field is conditionally required or not, and (b) to express the context in which a functional view is in effect."
category: "reference"
related:
    - "/finspec/reference"
---

## 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)**](https://en.wikipedia.org/wiki/Disjunctive_normal_form) 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)"_.

```jsonSchema protocol=finspec version=5.2 def=condition
{
    "type": [
        "object",
        "null"
    ],
    "description": "Machine-readable description of a condition which evaluates to true or false.",
    "additionalProperties": false,
    "properties": {
        "or": {
            "description": "A list of logical OR condition groups, at least ONE of which must evaluate to true in order for the overall condition to be true.",
            "type": "array",
            "items": {
                "type": "object",
                "description": "A sub-condition of the condition descrption.",
                "required": [
                    "and"
                ],
                "additionalProperties": false,
                "properties": {
                    "and": {
                        "description": "A list of logical AND conditions, ALL of which must evaluate to true in order for the sub-condition to be true.",
                        "type": "array",
                        "items": {
                            "type": "object",
                            "required": [
                                "tag",
                                "operator"
                            ],
                            "description": "A single condition node within a logical AND group.",
                            "additionalProperties": false,
                            "properties": {
                                "tag": {
                                    "description": "The field to which this condition applies.",
                                    "type": [
                                        "string",
                                        "integer"
                                    ]
                                },
                                "operator": {
                                    "type": "string",
                                    "enum": [
                                        "present",
                                        "not_present",
                                        "equals",
                                        "not_equals",
                                        "one_of",
                                        "not_in",
                                        "equals_field",
                                        "not_equals_field",
                                        "starts_with",
                                        "ends_with",
                                        "contains",
                                        "regex",
                                        "not_regex",
                                        "gt",
                                        "gte",
                                        "lt",
                                        "lte",
                                        "gt_field",
                                        "gte_field",
                                        "lt_field",
                                        "lte_field"
                                    ],
                                    "description": "The operator to apply to the field specified in the tag."
                                },
                                "reference": {
                                    "description": "A reference field value to be used for dynamic comparison (if applicable).",
                                    "type": [
                                        "string",
                                        "null"
                                    ]
                                },
                                "value": {
                                    "description": "A fixed value to compare the field against (if applicable).",
                                    "type": [
                                        "string",
                                        "null"
                                    ]
                                },
                                "text": {
                                    "type": "string",
                                    "description": "A human-readable description of this condition node."
                                },
                                "or_missing": {
                                    "type": "boolean",
                                    "description": "Indicates whether this condition should be considered true if the field is missing."
                                }
                            },
                            "$refName": "conditionNode",
                            "$refResolved": true
                        },
                        "minItems": 1
                    }
                },
                "$refName": "conditionAndGroup",
                "$refResolved": true
            },
            "minItems": 1
        }
    }
}
```

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.

| `operator`       |       `value`        |     `reference`      |
| ---------------- | :------------------: | :------------------: |
| present          |  :color:omit:grey:   |  :color:omit:grey:   |
| not_present      |  :color:omit:grey:   |  :color:omit:grey:   |
| equals           | :color:required:red: |  :color:omit:grey:   |
| not_equals       | :color:required:red: |  :color:omit:grey:   |
| one_of           | :color:required:red: |  :color:omit:grey:   |
| not_in           | :color:required:red: |  :color:omit:grey:   |
| starts_with      | :color:required:red: |  :color:omit:grey:   |
| ends_with        | :color:required:red: |  :color:omit:grey:   |
| contains         | :color:required:red: |  :color:omit:grey:   |
| regex            | :color:required:red: |  :color:omit:grey:   |
| not_regex        | :color:required:red: |  :color:omit:grey:   |
| gt               | :color:required:red: |  :color:omit:grey:   |
| gte              | :color:required:red: |  :color:omit:grey:   |
| lt               | :color:required:red: |  :color:omit:grey:   |
| lte              | :color:required:red: |  :color:omit:grey:   |
| equals_field     |  :color:omit:grey:   | :color:required:red: |
| not_equals_field |  :color:omit:grey:   | :color:required:red: |
| gt_field         |  :color:omit:grey:   | :color:required:red: |
| gte_field        |  :color:omit:grey:   | :color:required:red: |
| lt_field         |  :color:omit:grey:   | :color:required:red: |
| lte_field        |  :color:omit:grey:   | :color:required:red: |

[Table: Population of `value` and `reference` attributes based on `operator`]

### 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.
