X-04 · Run 144-rule validation

SOP: SOP_XBRL_Filing.md §6 / Step 4.0 (MAPPING_IN_PROGRESS → VALIDATION_PASSED | VALIDATION_FAILED)Actors: XBRL Reviewer (xbrl-reviewer@spade.local) or Senior Accountant — holds RUN_XBRL_VALIDATION. Pre-state: Filing at MAPPING_IN_PROGRESS. Every XbrlLineItem has a confirmed XbrlTagMapping (ideally — the validation engine still runs on partial confirmations but produces meaningless results). Post-state: XbrlValidationResult rows persisted. Filing at VALIDATION_PASSED (no ERROR-severity unpassed rows) or VALIDATION_FAILED.

0. Prerequisites

• Filing at MAPPING_IN_PROGRESS with confirmations complete (see X-03).
• Validation rules constitution loadable (loadValidationRules(taxonomyVersion) returns the 144 rules).

1. Steps

1.1 Trigger validation

POST /ops/xbrl/filings/<filingId>/validate
Authorization: Bearer <xbrl-reviewer-jwt>

(Or click Run validation on the Validation tab.)

The handler:

1. Asserts RUN_XBRL_VALIDATION.
2. Enqueues run-xbrl-validation with {xbrlFilingId, requestedBy}.
3. Returns 202 Accepted.

1.2 Worker — run-xbrl-validation

1. Loads every confirmed XbrlTagMapping for the filing.
2. Loads the validation rules for the pinned taxonomyVersion via loadValidationRules(version).
3. Filters by entry point via rulesForEntryPoint(version, entryPoint) — for FULL_XBRL typically ~100+ rules.
4. Evaluates each rule's expression against the line-item values + the taxonomy semantics (balance, period_type, data_type).
5. Deletes existing XbrlValidationResult rows for the filing (re-runs replace).
6. Inserts one XbrlValidationResult per rule: {ruleId, category, severity, passed, message, relatedElements, runAt}.
7. Computes the outcome:
   • VALIDATION_PASSED — no row with severity = ERROR AND passed = false
   • VALIDATION_FAILED — at least one such row
8. Transitions the filing accordingly.
9. Emits AuditEvent xbrl.validation.run with {ruleCount, errorCount, warningCount, infoCount}.

2. Verification

Database

SELECT severity, count(*) FILTER (WHERE passed = true) AS passed,
       count(*) FILTER (WHERE passed = false) AS failed
  FROM xbrl_validation_results
  WHERE xbrl_filing_id = '<filingId>'
  GROUP BY severity
  ORDER BY severity;

SELECT status FROM xbrl_filings WHERE id = '<filingId>';
-- expect 'VALIDATION_PASSED' or 'VALIDATION_FAILED'

Specific failures

SELECT rule_id, category, message, related_elements
  FROM xbrl_validation_results
  WHERE xbrl_filing_id = '<filingId>' AND severity = 'ERROR' AND passed = false
  ORDER BY rule_id;

Audit log

Event type	Notes
xbrl.validation.requested	API hit
xbrl.validation.run	Background completion; payload has rule + severity breakdown

UI

The Validation tab splits into three panes (Errors / Warnings / Info). Each row shows the rule id, category, message, and the elements it relates to. Failing errors are highlighted; reviewer can click into a row to see the underlying line items.

3. Negative & edge cases

• Validation run on an unconfirmed mapping — the rule evaluator includes only confirmed mappings; unconfirmed line items effectively count as missing for the purpose of mandatory-presence rules. Better to confirm everything first.
• Repeated runs — replace prior results (the upsert is keyed by (filingId, ruleId)).
• Caller without RUN_XBRL_VALIDATION — 403 Forbidden. XBRL_PREPARER cannot run validation by design (the action is part of the reviewer / senior boundary).
• Recovery loop — VALIDATION_FAILED → MAPPING_IN_PROGRESS is implicit: any subsequent mapping change automatically returns the filing to mapping. Re-run validation after fixes.
• Warning-only failures — filing still transitions to VALIDATION_PASSED. Warnings do not block but should be inspected; ACRA can still reject for warning-only issues.
• Unknown rule expression — handler logs the rule id and emits a WARNING result for the row; does not crash the whole run. This is a constitution-side bug; file an issue.

Next

Proceed to X-05 · Export BizFinx XLSX and XBRL XML.