Rules
ai_core.entities.RuleEntity represents a conditional configuration constraint.
Every IF condition must match before the THEN requirement applies. The rule type
determines the requirement for the THEN list. Neither object accepts a configurable
operator.
Schema
| Field | Meaning |
|---|---|
code | Source rule code, when available |
rule_type | Required inclusion, exclusion or only_one_of |
rule_if | Ordered IF parts, each with feature_code and negated; empty for only_one_of |
rule_then | Ordered THEN parts, each with feature_code |
validity | Nonempty list of date intervals; a slice with null bounds means all time |
rule_if and rule_then are lists and default to empty. Neither part accepts
an operator field.
Missing, null, or unsupported rule types fail validation. negated defaults to
false; null is invalid. Array order is preserved.
The consolidated tier resolves both lists against the feature catalog through a
foreign key and writes the matched ids to rule_if_feature_ids and
rule_then_feature_ids. An id list names the features a clause mentions and
states no polarity, which negated on the IF part supplies.
Conditions and consequences
Every IF part must be satisfied: a non-negated feature must be selected, and a negated feature must be absent. Here A, B, and C represent feature codes:
A AND B AND NOT C
When the conditions match:
| Rule type | THEN feature codes D, E mean | Equivalent requirement |
|---|---|---|
inclusion | Select at least one of D and E | D OR E |
exclusion | Select neither D nor E | NOT D AND NOT E |
only_one_of | Select at most one of D and E | NOT (D AND E) |
“At least one” permits both features unless another constraint forbids that
combination. Excluding D and E forbids each feature individually; it does not
merely forbid selecting them together. A excludes [D, E] therefore has the
same allowed configurations as A excludes D plus A excludes E.
For only_one_of, rule_then names a set rather than a consequence. The rule
permits a configuration to hold no more than one of its codes. Its rule_if must
be empty, and a rule that names an IF part fails validation. The restriction
therefore applies to every configuration under the rule's model key.
only_one_of [D, E, F] permits the same configurations as
D excludes [E, F], E excludes [D, F] and F excludes [D, E] together. A
consumer reads the set from the one row instead of reassembling it from the
three exclusions.
An only_one_of limits how many of its codes are selected and never requires
one. An inclusion and an only_one_of over the same codes together require
exactly one of them. The inclusion holds whatever IF parts scope the
requirement; the only_one_of applies under the model key alone.
For matched IF parts, the truth table is:
| D selected | E selected | inclusion satisfied | exclusion satisfied | only_one_of satisfied |
|---|---|---|---|---|
| No | No | No | Yes | Yes |
| Yes | No | Yes | No | Yes |
| No | Yes | Yes | No | Yes |
| Yes | Yes | Yes | No | No |
When IF does not match, this rule imposes no THEN requirement. An empty IF list
matches unconditionally. An empty inclusion THEN list cannot be satisfied when
IF matches; an empty exclusion THEN list imposes no restriction. An
only_one_of THEN list of fewer than two codes permits every configuration,
because no pair of its codes can conflict.
The ingestion schema stores these constraints. It does not evaluate a configuration or change its selected features.
Example
This rule says: if A is selected and B is absent, require C or D.
{
"code": "example",
"rule_type": "inclusion",
"rule_if": [
{"feature_code": "A", "negated": false},
{"feature_code": "B", "negated": true}
],
"rule_then": [
{"feature_code": "C"},
{"feature_code": "D"}
],
"validity": [{"valid_from": null, "valid_to": null}]
}
Validity
Each ValiditySlice contains nullable valid_from and valid_to date bounds.
A null bound is unrestricted. A rule applies when the date falls within at least
one slice. Omitted or empty validity normalizes to one slice with both bounds
null, representing all time.
Invalid dates and reversed bounds fail validation. The interval belongs to the
whole rule; individual parts have no timing fields.
Source references and enrichment
The common schema holds feature_code references. Source-specific transformed
schemas can retain OEM code references, including family codes and codes
absent from the feature catalog. Enrichment rewrites family references into
their member codes before rules enter consolidation, and the consolidated
foreign key resolves the codes into ids.
A family reference denotes the selection of a member of that family. Family expansion must preserve the fixed IF and THEN semantics:
| Reference position | Expansion |
|---|---|
| Positive IF family | Separate rules, one for each member condition |
| Negated IF family | Every member appears as a negated condition |
| Inclusion THEN family | All members become alternatives in the THEN list |
| Exclusion THEN family | All members appear in the forbidden THEN list |
only_one_of THEN family | All members appear in the THEN list |
For example, if family F contains A and B, F requires C becomes
A requires C and B requires C. Putting A and B together in one IF list would
require both and change the meaning. Multiple positive family conditions produce
one rule for each combination of member conditions.
Expansion alone does not limit selection to one feature per family or require a
family selection. Where a family's members cannot be selected together, an
only_one_of over its member codes states the restriction.
Unknown-reference handling depends on the catalog policy. Treating an absent reference as unselectable affects the whole rule: an unknown positive condition makes IF false, while an unknown negative condition is satisfied. Each source rule needs a recorded outcome so discarded rules remain traceable.
When a source treats absent codes as unselectable, discard a source rule when all its
THEN codes are absent from the catalog for its model and trim. Treat it as
inapplicable to that model and trim. Do not preserve an empty inclusion or infer an
exclusion of its subject.
Consolidation
Rules are optional in ConsolidatedComponent. Omitting its rules block builds
no rules asset. A configured rules entity receives rule_id using its
key_fields; each pipeline configures matching and model foreign keys. Foreign
keys may only target entities configured in the same component.
Rule parts hold feature_code values, and the foreign key resolves them into
rule_if_feature_ids and rule_then_feature_ids. The dependency graph is per
entity, so feature consolidation produces the feature catalog used by rule
enrichment. Rule consolidation then consumes the enriched rules. See
ConsolidatedComponent for configuration and
Foreign Keys for reference resolution.