Requirements Model

The FOCUS Requirements Model is a machine-readable representation of FOCUS normative requirements for a given version. It defines applicability criteria, check functions, dataset entry points, and requirement dependencies used to evaluate dataset conformance.

atlon.io ships two model artifacts:

The two models share the same overall shape, but 1.3 introduces a second dataset (ContractCommitment), a new entity type (Object for nested JSON schemas like ContractApplied and AllocatedMethodDetails), and a different rule-ID prefix scheme. Where the two diverge, this guide notes which version a snippet describes.

Model structure

The JSON file has five top-level sections. The 1.3 shape:

{
  "Details":               { "ModelVersion": "1.3", "FOCUSVersion": "1.3" },
  "ApplicabilityCriteria": { /* 20 applicability criteria */ },
  "CheckFunctions":        { /* function definitions */ },
  "ModelDatasets":         {
    "CostAndUsage":       { "ModelRules": ["CAU-CostAndUsage-D-000-M"] },
    "ContractCommitment": { "ModelRules": ["CCT-ContractCommitment-D-000-M"] }
  },
  "ModelRules":            { /* 933 rule definitions */ }
}

The 1.2 shape is the same except ModelDatasets lists a single entry (CostAndUsage, root rule CostAndUsage-D-000-M), ApplicabilityCriteria has 18 entries, and ModelRules has 621 entries.

Source of truth and build pipeline

The Requirements Model originates from the FOCUS_Spec repository. The upstream source files live under specification/requirements_model/:

The upstream build_json.py script merges all source files into a single build/model-{version}.json artifact. That built artifact is what ships in the validator.

Requirements Model integrity

The upstream Requirements Model test suite enforces these invariants:

• Every ModelRuleId referenced in a Requirement or Condition CheckModelRule must appear in that rule's Dependencies array
• Every -C-000- column composite must list its column's presence rule in Dependencies: CostAndUsage-D-* in 1.2; CAU-CostAndUsage-D-* or CCT-ContractCommitment-D-* in 1.3
• Rule IDs follow strict {Reference}-{EntityCode}-{NNN}-{ArtifactStatus} format
• The artifact status suffix (M/C/O) is consistent with requirement level classification (Mandatory, Conditional, Optional)

These guarantees ensure dependency integrity and referential consistency across the model graph.

Rule anatomy

Every rule has this structure (1.3 example):

"CAU-BilledCost-C-001-M": {
  "Function": "Type",
  "Reference": "BilledCost",
  "EntityType": "Column",
  "Notes": "",
  "ModelVersionIntroduced": "1.2",
  "Status": "Active",
  "ApplicabilityCriteria": [],
  "Type": "Static",
  "ValidationCriteria": {
    "MustSatisfy": "BilledCost MUST be of type Decimal.",
    "Keyword": "MUST",
    "Requirement": {
      "CheckFunction": "TypeDecimal",
      "ColumnName": "BilledCost"
    },
    "Condition": {},
    "Dependencies": []
  }
}

In 1.2 the same rule is keyed BilledCost-C-001-M (no dataset prefix). The body is otherwise identical.

Rule ID convention

Every rule ID follows the pattern:

[{DatasetPrefix}-]{Reference}-{EntityCode}-{SequenceNumber}-{ArtifactStatus}

The leading DatasetPrefix segment is 1.3 only. 1.2 has a single dataset, so its rule IDs omit the prefix.

Examples:

Note: the ArtifactStatus suffix reflects the requirement level classification in the model artifact, not the RFC keyword of an individual requirement statement.

Rule hierarchy

The model is a directed acyclic graph (DAG) of AND/OR composites with leaf rules at the bottom. 1.2 has one root (CostAndUsage-D-000-M); 1.3 has one root per dataset — CAU-CostAndUsage-D-000-M and CCT-ContractCommitment-D-000-M. A given validation run walks the DAG rooted at the dataset you selected.

The four-tier shape, shown with 1.3 rule IDs:

Tier 0: CAU-CostAndUsage-D-000-M          Root composite (AND)            [1.3]
        CCT-ContractCommitment-D-000-M    Root composite (AND)            [1.3, separate dataset]
        CostAndUsage-D-000-M              Root composite (AND)            [1.2 equivalent]
  |
  +-- Tier 1a: …D-001-M                   Presence composite (AND of every D-NNN-* under it)
  |     +-- CAU-CostAndUsage-D-006-M      ColumnPresent("BilledCost")           [MUST]
  |     +-- CAU-CostAndUsage-D-007-C      ColumnPresent("BillingAccountType")   [Conditional]
  |     +-- CAU-CostAndUsage-D-035-M      ColumnPresent("BillingCurrency")      [MUST]
  |     +-- ... (71 presence rules under CAU in 1.3; 13 under CCT; 63 in 1.2)
  |
  +-- Tier 1b: …D-002-M                   Validation composite (AND of all C-000 composites)
        +-- CAU-BilledCost-C-000-M         Column composite (AND)
        |     +-- CAU-BilledCost-C-001-M   Type check
        |     +-- CAU-BilledCost-C-002-M   Format check
        |     +-- CAU-BilledCost-C-003-M   Nullability check
        |     +-- CAU-BilledCost-C-004-M   Validation check
        |     +-- CAU-BilledCost-C-005-C   Conditional validation
        |     +-- CAU-BilledCost-C-006-M   Dynamic (skipped)
        |     +-- CAU-BilledCost-C-007-M   Dynamic (skipped)
        |
        +-- CAU-BillingCurrency-C-000-M    Column composite (AND)
        |     +-- ...
        +-- ... (one composite per column in the dataset)

Tier 0 is the dataset root (one per dataset). Tier 1a checks "are all required columns present?" Tier 1b checks "do column values pass?" Each column composite (Tier 2) groups its leaf rules (Tier 3) with an AND. The two dataset DAGs in 1.3 share leaf rules where columns overlap (BillingCurrency is present in both CAU and CCT).

Rule types

Presence

Checks whether a column exists in the dataset. These are Dataset-level rules (EntityType: "Dataset"). 1.3 example:

"CAU-CostAndUsage-D-006-M": {
  "Function": "Presence",
  "Reference": "BilledCost",
  "EntityType": "Dataset",
  "ValidationCriteria": {
    "MustSatisfy": "BilledCost MUST be present in a FOCUS dataset.",
    "Requirement": { "CheckFunction": "ColumnPresent", "ColumnName": "BilledCost" }
  }
}

If a column is missing, all downstream rules for that column are automatically failed/skipped.

Type

Checks the column's data type. Three check functions:

"CAU-BilledCost-C-001-M": {
  "Function": "Type",
  "ValidationCriteria": {
    "Requirement": { "CheckFunction": "TypeDecimal", "ColumnName": "BilledCost" }
  }
}

Format

Checks value patterns and formats. Six format check functions:

Additional specialized check:

• CheckNationalCurrency — validates against ISO 4217 currency code list

Nullability

Checks null handling. Reuses CheckNotValue or CheckValue with Value: null:

"CAU-BilledCost-C-003-M": {
  "Function": "Nullability",
  "ValidationCriteria": {
    "MustSatisfy": "BilledCost MUST NOT be null.",
    "Keyword": "MUST NOT",
    "Requirement": { "CheckFunction": "CheckNotValue", "ColumnName": "BilledCost", "Value": null }
  }
}

Some nullability rules are conditional, "column MUST be null when another column has a specific value":

"CAU-CommitmentDiscountName-C-004-C": {
  "Function": "Nullability",
  "ValidationCriteria": {
    "MustSatisfy": "CommitmentDiscountName MUST be null when CommitmentDiscountId is null.",
    "Requirement": { "CheckFunction": "CheckValue", "ColumnName": "CommitmentDiscountName", "Value": null },
    "Condition": { "CheckFunction": "CheckValue", "ColumnName": "CommitmentDiscountId", "Value": null }
  }
}

Validation

Business logic checks on data values. Uses various check functions:

Example — conditional cross-column validation:

"CAU-BilledCost-C-005-C": {
  "Function": "Validation",
  "ValidationCriteria": {
    "MustSatisfy": "BilledCost MUST be 0 where ProviderName != InvoiceIssuerName.",
    "Requirement": { "CheckFunction": "CheckValue", "ColumnName": "BilledCost", "Value": 0 },
    "Condition": { "CheckFunction": "CheckNotSameValue",
                   "ColumnAName": "ProviderName", "ColumnBName": "InvoiceIssuerName" },
    "Dependencies": ["CAU-ProviderName-C-000-M", "CAU-InvoiceIssuerName-C-000-M"]
  }
}

Composite

Logical grouping of child rules using AND or OR. Composites reference children via CheckModelRule:

"CAU-BilledCost-C-000-M": {
  "Function": "Composite",
  "ValidationCriteria": {
    "Requirement": {
      "CheckFunction": "AND",
      "Items": [
        { "CheckFunction": "CheckModelRule", "ModelRuleId": "CAU-BilledCost-C-001-M" },
        { "CheckFunction": "CheckModelRule", "ModelRuleId": "CAU-BilledCost-C-002-M" },
        { "CheckFunction": "CheckModelRule", "ModelRuleId": "CAU-BilledCost-C-003-M" },
        ...
      ]
    },
    "Dependencies": [
      "CAU-CostAndUsage-D-006-M",
      "CAU-BilledCost-C-001-M", "CAU-BilledCost-C-002-M", "CAU-BilledCost-C-003-M", ...
    ]
  }
}

• AND composites pass only if ALL children pass
• OR composites pass if ANY child passes (used for complex applicability logic)

Object (1.3+)

Some FOCUS 1.3 columns hold nested JSON whose internal structure is itself part of the spec, like ContractApplied and AllocatedMethodDetails today. These are represented as a separate Object entity (EntityType: "Object", EntityCode O in the rule ID) with their own composite tree. Object rules use JSONCheckPathType to walk a JSONPath inside the column value:

"CAU-ContractAppliedObject-O-020-M": {
  "Function": "Type",
  "EntityType": "Object",
  "ValidationCriteria": {
    "MustSatisfy": "\"ContractId\" MUST be of type String.",
    "Requirement": {
      "CheckFunction": "JSONCheckPathType",
      "ColumnName": "ContractApplied",
      "Path": "$.Elements[*].ContractId",
      "ExpectedType": "String"
    }
  }
}

The wrapping column composite (e.g. CAU-ContractApplied-C-000-C) depends on the object composite (CAU-ContractAppliedObject-O-000-C), so a malformed nested JSON value cascades up to the column-level result.

Dependencies and execution order

How dependencies work

Dependencies are declared in three ways:

1. Structural: composite rules implicitly depend on their children (via CheckModelRule references in Items)
2. Explicit: rules list other rule IDs in their Dependencies array (e.g., a conditional validation that needs another column's composite to pass first)
3. Presence gating: the engine's post-processing automatically cascades presence failures to all rules for that column

Execution sequence for a column

The dependency graph produces this execution order per column (1.3 rule IDs shown; 1.2 omits the CAU- prefix):

1. CAU-CostAndUsage-D-006-M    Presence     "Is BilledCost present?"
       | (if absent, everything below cascades to fail/skip)
2. CAU-BilledCost-C-001-M      Type         "Is it Decimal?"
3. CAU-BilledCost-C-002-M      Format       "Matches NumericFormat?"
4. CAU-BilledCost-C-003-M      Nullability  "No nulls?"
5. CAU-BilledCost-C-004-M      Validation   "Valid decimal values?"
6. CAU-BilledCost-C-005-C      Validation   "BilledCost=0 when ProviderName != InvoiceIssuerName?"
7. CAU-BilledCost-C-006-M      Dynamic      --> SKIPPED
8. CAU-BilledCost-C-007-M      Dynamic      --> SKIPPED
       | (all results aggregated)
9. CAU-BilledCost-C-000-M      Composite    AND of rules 2-8

The engine builds a topological sort of the full DAG and processes rules layer by layer. Rules in the same layer (no dependencies between them) could theoretically run in parallel.

Cross-column dependencies

Some rules depend on other columns being validated first. For example, CAU-BilledCost-C-005-C depends on CAU-ProviderName-C-000-M and CAU-InvoiceIssuerName-C-000-M because its condition references both columns. This means the entire ProviderName and InvoiceIssuerName validation must complete before this rule can execute.

Gating mechanisms

Three mechanisms control whether a rule applies:

1. Applicability criteria (dataset-level gate)

Provider capability flags that enable or disable entire groups of rules. If a provider doesn't support a feature, the related rules are marked non-applicable and skipped.

"CAU-CostAndUsage-D-007-C": {
  "Function": "Presence",
  "Reference": "BillingAccountType",
  "ApplicabilityCriteria": ["MULTIPLE_BILLING_ACCOUNT_TYPES_SUPPORTED"]
}

1.2 has 18 applicability criteria; 1.3 adds two more (CONTRACT_COMMITMENTS_SUPPORTED, DATA_GENERATOR_SPLIT_COST_ALLOCATION_SUPPORTED) for a total of 20:

When a presence rule is non-applicable, ALL downstream rules for that column are also marked non-applicable.

2. Conditions (row-level gate)

A rule can have a Condition that limits which rows it applies to:

"Condition": {
  "CheckFunction": "CheckNotSameValue",
  "ColumnAName": "ProviderName",
  "ColumnBName": "InvoiceIssuerName"
}

The rule is only evaluated on rows where the condition is true. Rows that don't match are excluded from violation counts.

3. Static vs Dynamic (automatable gate)

• Static rules have a Requirement with a CheckFunction and can be executed automatically via SQL
• Dynamic rules have an empty Requirement: {} and represent requirements that need human judgment or external data (e.g., "BilledCost MUST be denominated in BillingCurrency" requires knowing the actual currency of each charge)

Dynamic rules are always skipped during automated validation and reported as informational.

Requirement keywords

The Keyword field uses BCP 14 terminology (RFC 2119 and RFC 8174) and drives skip behavior:

Validation modes

The engine supports two validation modes via the mode query parameter:

The active rule count depends on the version and dataset you pick:

Schema mode reads only the CSV header row (csv.reader, one next()) or Parquet schema (pyarrow.parquet.read_schema), then compares against expected columns from the FOCUS model metadata. Zero data rows are loaded, making it near-instant on any file size.

Column reference

The two model versions differ in their column rosters. FOCUS 1.2 has a single dataset with 57 columns. FOCUS 1.3 grows CostAndUsage to 65 columns and introduces a separate ContractCommitment dataset with 13 columns (BillingCurrency is shared between the two datasets, so the unique-column total is 77).

FOCUS 1.2 — CostAndUsage (57 columns)

The model contains 63 Presence rules due to conditional variants.

Mandatory columns (always required)

Conditionally required columns (based on provider capabilities)

Optional columns

FOCUS 1.3 — CostAndUsage (65 columns)

The 1.3 CostAndUsage dataset retains every 1.2 column and adds 8 new ones (HostProviderName, ServiceProviderName, ContractApplied, and the five Allocated* fields). The model contains 71 Presence rules: 65 columns plus 6 conditional variants. ContractApplied and AllocatedMethodDetails are validated as nested-JSON Object schemas (see the Object rule type above for how their internal shape is enforced).

Mandatory columns (always required)

Conditionally required columns (based on provider capabilities)

Optional columns

FOCUS 1.3 — ContractCommitment (13 columns)

The ContractCommitment dataset describes the contracts and commitments that CostAndUsage charges roll up to. All 13 columns are mandatory; none gate on applicability criteria. BillingCurrency is the only column shared with CostAndUsage. There are no conditional or optional columns in this dataset.

Mandatory columns (always required)