Fact Definitions

What is a Fact Definition?

A Fact Definition declares an input variable that your rules can reference in conditions and actions. Think of it like a function parameter — you define the name and type before writing the logic. Facts are tenant-wide: once defined, they’re available across all policy groups and versions.

Pre-registered Facts

Every tenant starts with these pre-registered facts, available immediately after account creation:

Key	Type	Description
`userId`	STRING	User identifier
`userTags`	LIST_STRING	User tags
`isBlocked`	BOOLEAN	`true` when a `BLOCK` action ran
`blockReason`	STRING	The `reason` of the `BLOCK` action, or `Policy Violation` if it has none

userId and userTags are provided for convenience — they are regular facts, not protected. You can rename, retype, or delete them exactly as you would any custom fact, under the same rule (see Managing Facts). They can be used in conditions and actions immediately, with no registration needed. isBlocked and blockReason are system facts. They hold the values the BLOCK action writes, so the engine fixes their shape:

You cannot delete them or change their type (FD-003).
No SET_FACT or MUTATE_FACT can target them (ACT-033). Only BLOCK writes them.
You can still rename them, change their description, mark them as PII, and give blockReason a value domain.

A condition can use them, but it reads only the value your request sends. It never sees what BLOCK writes during the same request (see How a request runs). To use a previous call’s block in a condition, send it under another key such as previouslyBlocked. If you send isBlocked: true and BLOCK writes true again, the value does not change, so it comes back in neither mutatedFacts nor generatedVariables.

Custom Facts

Any input variable beyond the pre-registered facts should be registered before use (see Unregistered Facts). For example, customerTier, orderRegion, or productCategory are custom facts.

lexq facts create --key customerTier --name "Customer Tier" --type STRING
lexq facts create --key orderRegion --name "Order Region" --type STRING --required
lexq facts create --key customerEmail --name "Customer Email" --type STRING --pii

Supported Types

Type	JSON	Example Value
`STRING`	`"string"`	`"VIP"`
`NUMBER`	`number`	`100000`
`BOOLEAN`	`true / false`	`true`
`LIST_STRING`	`["a", "b"]`	`["KR", "US"]`
`LIST_NUMBER`	`[1, 2]`	`[10000, 20000]`

Value Domains

A type says a fact holds a number. A value domain says which numbers. Declare one and the platform refuses a rule that could never match, and the rule editor offers a dropdown instead of a free text box.

Type	`allowedValues`	`min` / `max`
`STRING`	✅	—
`NUMBER`	✅	✅
`BOOLEAN`	—	—
`LIST_STRING`	✅ per element	—
`LIST_NUMBER`	✅ per element	✅ per element

BOOLEAN takes neither — it has only two values to begin with. For list types the value domain applies to each element, not to the list as a whole.

lexq facts create --key riskScore --name "Risk Score" --type NUMBER --min 0 --max 100
lexq facts create --key tier --name "Tier" --type STRING \
  --allowed-values "GOLD, SILVER, BRONZE"

Every field is optional. Leave them all out and the fact behaves exactly as it did before.

What changes once you declare one

Saving a rule. A literal outside the domain is refused, so tier == "PLATNUM" is caught at save time instead of silently never matching.
Writing a rule. The console turns the value box into a dropdown for scalar types.
Executing. An input value outside the domain returns 400. Before, sending an out-of-domain value was more permissive than omitting the fact — omitting one the rules read was already a 400.

Comparison operators are checked against min and max only. A boundary need not be one of the allowed values: loyaltyPoints > 50 is valid even when the allowed values are [0, 100, 200], because 50 is a threshold, not a value the fact will hold. CONTAINS is exempt entirely. tier CONTAINS "OLD" legitimately matches "GOLD", and "OLD" is not an allowed value.

Changing a domain later

Execution reads the copy taken when the version was published, not today’s definition.

Changing a domain does not touch a version that is already published, including one you deploy or roll back to later. The change reaches execution once you publish a new version and deploy it.
Changing a domain never rewrites a rule, and it never blocks the update, even when rules use values the new domain does not accept. The update lists those rules instead.

Declare the domain when you create the fact. Rules written afterwards get the dropdown, and the typos a domain catches are the ones that are hardest to notice — a rule that saves cleanly and then never fires.

Rules outside a changed domain

When an update changes a fact’s value domain (declares one, narrows it, or replaces it), LexQ checks the rules that compare that fact, using the same check that runs when a rule is saved (P-051). The rules whose conditions use a value the new domain does not accept come back with the update.

Which versions. Drafts, and the versions currently deployed: each group’s live version and its A/B test version. Versions that are only published, versions whose effective window has ended, and versions in deleted groups are left out. You cannot edit them, and they keep the copy taken when they were published.
How much. Every version is listed. Each shows up to five rules in priority order, with every affected condition exactly as the rule has it, and counts the rest. Disabled rules are included.
When. Only when the update changes the stored domain. Sending the same domain again lists nothing. Removing a domain lists nothing either, because no value is outside it.

What a listed version needs depends on its kind:

Version	What happens to the listed rules	What to do
Draft	A request that sends one of these values is rejected with `P-052` before any rule is checked: in this draft’s dry runs now, and in live calls once it is published and deployed. Saving the rule again fails with `P-051` until the condition is edited or removed.	Check whether each condition is still needed, then edit or remove it.
Deployed	Calls are checked against the definitions copied at publish, so nothing changes yet.	Cloning the version carries these rules into the new draft, and neither cloning nor publishing checks condition values again. Fix them in the clone before you publish it.

Do not just swap in an allowed value. After BRONZE is removed from tier, tier NOT_EQUALS "BRONZE" is true for every allowed tier, while tier NOT_EQUALS "SILVER" would start excluding silver customers. Where the list appears:

Surface	What you see
Console	Saving the fact opens a dialog, N rules use values outside the new value domain, grouped by version, with Open version for each
CLI 1.1.6+	`lexq facts update` prints the list to stderr. stdout is still the JSON of the updated fact, so piping it keeps working
MCP	The result of `lexq_facts_update` ends with the same text, on `mcp.lexq.io` and in the stdio server of CLI 1.1.6+
API	The update response carries `meta.valueDomainMismatch`. With no listed rules, the response has no `meta`

Removing BRONZE from the allowed values of tier prints the updated fact on stdout and this on stderr:

$ lexq facts update --id <factId> --allowed-values "GOLD, SILVER"
⚠ 3 rules compare tier with values the new value domain does not accept. The update was still saved.
  "Loyalty discounts" v3, draft (groupId 8f14e45f-ceea-4e67-9b3f-1c2d3e4f5a6b, versionId c9f0f895-fb98-4b9a-8f2e-0a1b2c3d4e5f)
    Dry runs of this draft already reject calls that send these values (P-052), and live calls will too once it is published and deployed. Saving one of these rules again is refused (P-051) until each listed condition is edited or removed; first check whether each one is still needed.
    • "Bronze welcome" (ruleId 45c48cce-2e2d-4fbd-a2f1-6a7b8c9d0e1f): tier EQUALS "BRONZE"
    • "Upsell above bronze" (ruleId d3d94468-02a4-4b49-9d5e-7f8a9b0c1d2e): tier NOT_EQUALS "BRONZE"
  "Loyalty discounts" v2, deployed (groupId 8f14e45f-ceea-4e67-9b3f-1c2d3e4f5a6b, versionId 6512bd43-d9ca-46e0-8d2a-3b4c5d6e7f80)
    Calls to it are checked against the fact definitions captured when it was published, so this change does not affect them. A version cloned from it carries these rules; fix them in the clone before publishing it.
    • "Bronze welcome" (ruleId c20ad4d7-6fe9-4759-8a1b-2c3d4e5f6a7b): tier EQUALS "BRONZE"

API response: meta.valueDomainMismatch

meta of the update response for the same example. data holds the updated fact.

{
  "valueDomainMismatch": {
    "factKey": "tier",
    "totalRuleCount": 3,
    "versions": [
      {
        "groupId": "8f14e45f-ceea-4e67-9b3f-1c2d3e4f5a6b",
        "groupName": "Loyalty discounts",
        "versionId": "c9f0f895-fb98-4b9a-8f2e-0a1b2c3d4e5f",
        "versionNo": 3,
        "versionStatus": "DRAFT",
        "ruleCount": 2,
        "rules": [
          {
            "ruleId": "45c48cce-2e2d-4fbd-a2f1-6a7b8c9d0e1f",
            "ruleName": "Bronze welcome",
            "conditions": [{ "operator": "EQUALS", "value": "BRONZE" }]
          },
          {
            "ruleId": "d3d94468-02a4-4b49-9d5e-7f8a9b0c1d2e",
            "ruleName": "Upsell above bronze",
            "conditions": [{ "operator": "NOT_EQUALS", "value": "BRONZE" }]
          }
        ]
      },
      {
        "groupId": "8f14e45f-ceea-4e67-9b3f-1c2d3e4f5a6b",
        "groupName": "Loyalty discounts",
        "versionId": "6512bd43-d9ca-46e0-8d2a-3b4c5d6e7f80",
        "versionNo": 2,
        "versionStatus": "ACTIVE",
        "ruleCount": 1,
        "rules": [
          {
            "ruleId": "c20ad4d7-6fe9-4759-8a1b-2c3d4e5f6a7b",
            "ruleName": "Bronze welcome",
            "conditions": [{ "operator": "EQUALS", "value": "BRONZE" }]
          }
        ]
      }
    ]
  }
}

Field	Meaning
`factKey`	The fact that was updated
`totalRuleCount`	Affected rules across all versions, including those beyond the five shown. A rule that a draft copied from a deployed version counts once in each
`versions[].versionStatus`	`DRAFT`, or `ACTIVE` for a deployed version
`versions[].ruleCount`	Affected rules in that version. It can be larger than the length of `rules`
`versions[].rules`	Up to five rules in priority order. `conditions` holds each affected condition’s `operator` and `value` as written

Naming Conventions

A fact key starts with a letter, then letters, numbers, and underscores. Keys are case-sensitive, so paymentAmount and paymentamount are two different facts. Casing is yours to choose. LexQ’s own facts and every example in these docs use camelCase, but the engine accepts any casing, and a key you already created keeps working.

✅ paymentAmount, customerTier, userRegion
✅ payment_amount, PAYMENT_AMOUNT — valid too, just not what these docs show
❌ Payment-Amount, PAYMENT AMOUNT, 1stPurchase, _internal

Required vs Optional Facts

The rules decide which keys a request must send, not the fact definition. Every key that an enabled rule in the executed version reads must be present in the request: its condition fields, and the targetVar and refVar of MUTATE_FACT. If one is missing, the request fails with P-015. To leave a value out on purpose, send the key with null. A condition on a null value does not match. A MUTATE_FACT target is the exception: when the action runs, its value must be a number. If it is null at that point, the request fails with P-003.

The Required flag on a fact definition is informational only. It has no effect at execution, and it will be removed.

PII Facts

A fact can be marked as PII (personally identifiable information) in the Console under Management → Fact Definitions, or with the CLI: --pii on lexq facts create or lexq facts update, and --no-pii to clear it. On update, both flags need CLI 1.1.6 or later. Marking changes how the value is read, not how rules run:

Rules evaluate the real value as usual — masking is aimed at humans and integrations, not at the engine.
On every read surface (Decision Provenance, execution history detail, exports) the value arrives masked as ••••••, and maskedKeys lists what was masked.
Revealing a masked value is console-only and audited: the audit row is written before the value is shown. See Decision Provenance for the full contract.

Mark facts like emails, phone numbers, and account identifiers as PII at creation time — masking starts the moment the flag is on, with no rule changes needed.

Unregistered Facts

A key that a rule only reads (a condition field, or a refVar) can be referenced before you register it as a Fact Definition. LexQ does not force registration first for those, but whenever you save a rule, it tells you which referenced keys are not in the schema. An action target is different. The targetVar of SET_FACT and MUTATE_FACT must be a registered fact. Saving or publishing a rule that writes to an unregistered key fails with ACT-032, so register the fact first. On every rule create or update, LexQ scans the rule’s conditions and actions and returns any unregistered facts — keys that no Fact Definition declares — each with an inferred type, a suggested display name, and where it was referenced (condition or action). For keys a rule only reads, this is non-blocking by design: saving, publishing, and deploying are not stopped. The rule is stored exactly as written. A key it reads must still be sent at execution, registered or not (see Required vs Optional Facts). What stays off until you register the fact:

Unregistered	Registered
The rule’s operator is not checked against a type	A rule whose operator does not fit the declared `STRING` / `NUMBER` / … type is rejected on save (`P-048`), simulation records are checked against that type (`AN-017`), and a request that sends another type is rejected before execution (`P-060`)
No autocomplete in the Console rule editor	Key suggested as you type
Listed in `lexq analytics requirements` and the dry-run requirements view with type `UNKNOWN`	Listed there with its declared type and display name

Registering a fact also adds a type check before execution. A request that sends another type for a registered fact the version reads, such as "85" for a NUMBER, fails with P-060 before any rule is checked. null is not a mismatch. Like the value domain, the check reads the declarations copied when the version was published, so a fact you register after a version is published is not checked in that version. A key that is not registered is never checked: the condition does not match, and that rule’s decisionTraces[].reasonDetail reads Evaluation error: FACT_TYPE_MISMATCH. The unregistered-fact warning surfaces on every authoring surface: the CLI (stderr), the Console rule editor and deploy dialog, and the MCP tools.

Reviewing and registering

A save returns its unregistered facts inline, but you can also list them for an entire version at any time:

lexq facts unregistered --group-id <gid> --version-id <vid>

Then register the ones you intend to keep:

lexq facts create --key orderRegion --name "Order Region" --type STRING

Registration is always an explicit step — LexQ never auto-creates a fact from a rule reference. Your schema stays a deliberate contract, not a side effect of rule authoring.

Managing Facts

Facts are managed in the Console under Management → Fact Definitions, or via the CLI:

lexq facts list
lexq facts create --key orderTotal --name "Order Total" --type NUMBER --required
lexq facts update --id <factId> --name "Total Order Amount"
lexq facts delete --id <factId>

An update changes only the fields you send, and the API and the MCP tool lexq_facts_update work the same way. Leave out --name or --description and it stays as it is. To remove a description, pass an empty one:

lexq facts update --id <factId> --description ""

A display name cannot be removed: an empty or blank name fails with C-001.

Use lexq analytics requirements (CLI) or the Engine API’s GET /groups/{groupId}/requirements endpoint to see exactly which facts a deployed version needs.

A fact that rules reference cannot be deleted, and its type cannot be changed. Both calls return 409 — FD-006 for the delete, FD-007 for the type change — and report how many rules reference it. Remove those references first, or create a new fact.This holds regardless of version status: a draft counts the same as a deployed version. Rules in a deleted group don’t count, because a deleted group can’t be edited or deployed. You can still replay a deleted group after you delete or retype the fact. Renaming a fact and toggling required are never blocked.System facts are the exception: deleting one or changing its type fails with FD-003 whether or not rules reference it.

Getting Started

Core Concepts

Features

What is a Fact Definition?

Pre-registered Facts

Custom Facts

Supported Types

Value Domains

What changes once you declare one

Changing a domain later

Rules outside a changed domain

Naming Conventions

Required vs Optional Facts

PII Facts

Unregistered Facts

Reviewing and registering

Managing Facts

Next Steps

Policy Rules

Policy Execution

​What is a Fact Definition?

​Pre-registered Facts

​Custom Facts

​Supported Types

​Value Domains

​What changes once you declare one

​Changing a domain later

​Rules outside a changed domain

​Naming Conventions

​Required vs Optional Facts

​PII Facts

​Unregistered Facts

​Reviewing and registering

​Managing Facts

​Next Steps

Policy Rules

Policy Execution

What is a Fact Definition?

Pre-registered Facts

Custom Facts

Supported Types

Value Domains

What changes once you declare one

Changing a domain later

Rules outside a changed domain

Naming Conventions

Required vs Optional Facts

PII Facts

Unregistered Facts

Reviewing and registering

Managing Facts

Next Steps