TG-VALIDATE-STRUCTURE
TrustGate Structure Validation Engine
0. Identity
Depends on module:
1. Purpose
The TrustGate Structure Validation Engine is the platform-wide structural validation micro-engine used by TrustGate to verify that parsed runtime signals conform to canonical ZAYAZ data contracts before they are normalized, enriched, scored, routed, replayed, anchored, or federated.
This engine is the first formal assurance gate after signal parsing.
It ensures that incoming payloads are not merely syntactically parseable, but structurally valid according to:
- CSI contracts;
- SSSR schemas;
- ZAR artifact references;
- ECO Number identity rules;
- CMI reference rules;
- DID and signature requirements;
- unit and datatype constraints;
- replay compatibility requirements;
- federation compatibility requirements.
The engine is designed as a platform-wide SIS validation primitive with TrustGate as its first consuming implementation. Other ZAYAZ modules may reuse the same validation rule registry, validation taxonomy, and event model.
2. Position within TrustGate Runtime
The Structure Validation Engine executes immediately after parsing and before normalization.
External Signal
│
▼
Signal Parser Engine
│
▼
──────────────────────────────────────────
Structure Validation Engine
──────────────────────────────────────────
│
▼
Signal Normalizer Engine
│
▼
Context Enrichment Engine
│
▼
Trust Scoring Engine
│
▼
Decision Engine
The engine does not transform payload values.
It validates structure and contract compliance.
If the payload passes validation, it is forwarded to normalization. If it fails validation, it is either rejected, quarantined, aborted, or routed for review according to the applicable validation rule action.
3. Platform Role
Although this engine is documented in the TrustGate Engine Catalog, its validation taxonomy is platform-wide.
It uses the following ZAR registries:
| Registry | Purpose |
|---|---|
zar.validation_rule_registry | Canonical validation rules and runtime actions. |
zar.validation_rule_domain | Controlled vocabulary for validation domains. |
zar.validation_rule_category | Controlled vocabulary for validation categories. |
zar.validation_rule_function | Controlled vocabulary for validation targets. |
zar.meid_registry | Stable logical micro-engine identities. |
zar.meid_cmi_binding | MEID to CMI implementation bindings. |
| ZAR CMI Registry | Canonical versioned software artifacts. |
| CSI Registry | Canonical signal interfaces. |
| SSSR Registry | Structural and semantic schema definitions. |
This makes the validation layer reusable across TrustGate, Input Hub, AAE, DAL, EIF, AFLE, EGFS, MICE, Reports Hub, and external federation nodes.
4. Canonical Identity
| Property | Value |
|---|---|
| Engine Name | TrustGate Structure Validation Engine |
| MEID | MEID_SIGNAL_VALIDATE_STRUCTURE |
| CMI | vera.TG-VALIDATE.ENGINE.STRUCTURE.1_0_0 |
| KIND | ENGINE |
| Runtime Type | Micro-Engine |
| Owner Module | Verification & Assurance |
| Platform Role | SIS validation primitive |
| Runtime Order | After parser, before normalizer |
| Replay Support | Native |
| DAL Anchoring | Yes |
| Federation Aware | Yes |
| Rule Registry | zar.validation_rule_registry |
The MEID identifies the stable logical engine.
The CMI identifies this specific versioned implementation.
5. Design Principles
| Principle | Description |
|---|---|
| Validate, Do Not Transform | The engine validates structure and contracts but does not change values. |
| Registry-Driven | Rules are loaded from ZAR validation registries. |
| Deterministic | The same input and rule version always produce the same output. |
| Replayable | Every validation result can be reproduced by OARM/AAE. |
| Explainable | Every failure must include a rule code, severity, field path, and action. |
| Platform-Wide | Rule taxonomy is reusable beyond TrustGate. |
| Federation-Aware | ECO, DID, CMI, CSI, and signatures are validated for cross-ECO exchange. |
| DAL-Compatible | Validation artifacts can be included in DAL hash batches. |
| Fail-Safe | Critical identity, schema, or signature failures result in rejection or abort. |
6. Runtime Responsibilities
| Validation Area | Description |
|---|---|
| Payload Structure | Object hierarchy, required sections, root object integrity. |
| JSON Syntax | Confirm syntactic validity of parsed JSON object. |
| Required Fields | Confirm mandatory fields exist. |
| Datatypes | Confirm field values match expected datatypes. |
| Enumerations | Confirm allowed values. |
| CSI Version | Confirm CSI exists and is supported. |
| CMI Reference | Confirm CMI exists in ZAR and is active. |
| MEID Reference | Confirm MEID exists and is properly bound. |
| Metric Type | Confirm metric type exists in the ZAYAZ metric registry. |
| Unit Validity | Confirm canonical unit and dimensional compatibility. |
| ECO Number | Confirm ECO Number format, existence, and status. |
| DID | Confirm DID syntax, controller, and verification method. |
| Signatures | Confirm payload signatures where required. |
| Timestamp | Confirm ISO-8601 and reporting-period validity. |
| Replay Compatibility | Confirm payload can be replayed deterministically. |
| Federation Compatibility | Confirm cross-ECO payload compatibility where applicable. |
7. Runtime Pipeline
Receive Parsed Signal
│
▼
Load Validation Profile
│
▼
Load CSI Contract
│
▼
Load Applicable Rules
│
▼
Validate Structure
│
▼
Validate Required Fields
│
▼
Validate Datatypes
│
▼
Validate References
│
▼
Validate Identity
│
▼
Validate Cryptographic Fields
│
▼
Validate Replay Compatibility
│
▼
Apply Rule Actions
│
▼
Emit Validation Result
The engine must stop immediately when a rule with action abort is triggered.
Rules with action reject, quarantine, review, or warn may be accumulated into a complete validation result, depending on runtime configuration.
8. Validation Rule Taxonomy
Validation rules use a platform-wide taxonomy.
<DOMAIN> / <CATEGORY> / <FUNCTION>
Examples:
| Rule Code | Domain | Category | Function |
|---|---|---|---|
TG-VAL-0001 | SIGNAL | STRUCTURE | JSON |
TG-VAL-0002 | SIGNAL | REQUIRED_FIELD | REQUIRED_FIELDS |
TG-VAL-0004 | SIGNAL | VERSION | CSI_VERSION |
TG-VAL-0005 | ENGINE | REFERENCE | CMI_REFERENCE |
TG-VAL-0007 | UNIT | COMPATIBILITY | UNIT_COMPATIBILITY |
TG-VAL-0008 | IDENTITY | FORMAT | ECO_NUMBER |
TG-VAL-0009 | IDENTITY | FORMAT | DID |
TG-VAL-0010 | CRYPTO | SIGNATURE | SIGNATURE |
TG-VAL-0011 | SIGNAL | DATATYPE | DATATYPE |
This taxonomy allows validation to be interpreted consistently across TrustGate, AAE, DAL, AFLE, EIF, and EGFS.
9. Canonical Validation Codes
| Rule Code | Canonical Name | Severity | Default Action |
|---|---|---|---|
TG-VAL-0001 | Invalid JSON Structure | critical | reject |
TG-VAL-0002 | Missing Required Field | error | quarantine |
TG-VAL-0003 | Invalid ECO Number | critical | abort |
TG-VAL-0004 | Invalid CSI Version | error | quarantine |
TG-VAL-0005 | Invalid CMI Reference | critical | reject |
TG-VAL-0006 | Unknown Metric Type | error | quarantine |
TG-VAL-0007 | Invalid Unit | error | quarantine |
TG-VAL-0008 | Invalid ECO Number | critical | abort |
TG-VAL-0009 | Invalid DID | critical | reject |
TG-VAL-0010 | Signature Verification Failed | critical | reject |
TG-VAL-0011 | Invalid Datatype | error | quarantine |
TG-VAL-0003 and TG-VAL-0008 currently overlap conceptually. Until the rule registry is normalized, TG-VAL-0003 should be treated as the general identity resolution rule and TG-VAL-0008 as the explicit ECO Number format/status rule.
10. Validation Algorithm
function validate_structure(parsed_signal):
profile = load_validation_profile(parsed_signal.signal_type)
csi_contract = load_csi_contract(parsed_signal.csi)
rules = load_active_rules(
applies_to_meid = "MEID_SIGNAL_VALIDATE_STRUCTURE",
input_csi = parsed_signal.csi
)
result = create_validation_result(parsed_signal)
for rule in ordered(rules):
evaluation = evaluate(rule, parsed_signal, csi_contract)
result.add(evaluation)
if evaluation.failed and rule.action == "abort":
result.status = "aborted"
break
result.final_action = resolve_final_action(result)
emit_validation_event(result)
return result
Rules are evaluated in deterministic order:
- critical identity and schema rules;
- structural rules;
- datatype rules;
- reference rules;
- unit and metric rules;
- cryptographic rules;
- replay and federation compatibility rules.
11. Action Resolution
If multiple validation rules fail, the final action is resolved by severity.
Action precedence:
abort
↓
reject
↓
quarantine
↓
review
↓
warn
↓
pass
Example:
If one rule returns warn and another returns quarantine, the final action is quarantine.
If any rule returns abort, execution terminates immediately.
12. CSI Contracts
12.1. Input CSIs
| CSI | Required | Description |
|---|---|---|
comp.TG.INPUT.PARSED-SIGNAL.v1_0 | Yes | Parsed signal emitted by the Signal Parser Engine. |
comp.SSSR.SCHEMA.REGISTRY.v1_0 | Yes | Schema metadata and structural contract lookup. |
comp.ZAR.INPUT.CMI-REFERENCE.v1_0 | Conditional | CMI references attached to source payloads. |
comp.EGFS.INPUT.IDENTITY-REFERENCE.v1_0 | Conditional | ECO Number, DID, and federation identity references. |
12.2. Output CSIs
| CSI | Description |
|---|---|
comp.TG.OUTPUT.VALIDATED-SIGNAL.v1_0 | Parsed signal marked as structurally valid. |
comp.TG.EVENT.VALIDATION-PASSED.v1_0 | Validation success event. |
comp.TG.EVENT.VALIDATION-FAILED.v1_0 | Validation failure event. |
comp.TG.EVENT.QUARANTINE-CANDIDATE.v1_0 | Quarantine candidate event. |
comp.TG.EVENT.VALIDATION-RULE-TRACE.v1_0 | Per-rule execution trace. |
The CSI names follow the canonical CSI format:
<csi_module>.<csi_component>.<csi_kind>.<csi_name>.<csi_version_maj>_<csi_version_min>
13. Canonical Input Object
{
"signal_id": "SIG-2026-00001472",
"event_id": "EVT-2026-000991",
"eco_number": "ECO-A123",
"did": "did:zayaz:ECO-A123",
"csi": "comp.TG.INPUT.PARSED-SIGNAL.v1_0",
"source_system": "SAP-S4",
"payload_type": "invoice",
"payload": {
"invoice_id": "INV-2026-001",
"supplier_id": "ECO-SUP-7781",
"amount": 2500.00,
"currency": "EUR",
"unit": "kg",
"metric_type": "ghg.scope3.cat1.purchased_goods"
},
"signature": {
"algorithm": "Ed25519",
"value": "eyJhbGciOiJFZERTQSJ9..."
},
"parsed_at": "2026-06-25T10:41:13Z"
}
14. Canonical Validation Result
{
"validation_id": "VAL-2026-000442",
"signal_id": "SIG-2026-00001472",
"engine_cmi": "vera.TG-VALIDATE.ENGINE.STRUCTURE.1_0_0",
"meid": "MEID_SIGNAL_VALIDATE_STRUCTURE",
"status": "passed",
"final_action": "pass",
"rules_checked": 42,
"rules_failed": 0,
"schema_version": "1.2.0",
"validated_at": "2026-06-25T10:41:14Z"
}
15. Validation Failure Result
{
"validation_id": "VAL-2026-000443",
"signal_id": "SIG-2026-00001473",
"engine_cmi": "vera.TG-VALIDATE.ENGINE.STRUCTURE.1_0_0",
"meid": "MEID_SIGNAL_VALIDATE_STRUCTURE",
"status": "failed",
"final_action": "quarantine",
"rules_checked": 42,
"rules_failed": 2,
"failures": [
{
"rule_code": "TG-VAL-0002",
"canonical_name": "Missing Required Field",
"severity": "error",
"action": "quarantine",
"field_path": "$.payload.metric_type",
"message": "Required field metric_type is missing."
},
{
"rule_code": "TG-VAL-0011",
"canonical_name": "Invalid Datatype",
"severity": "error",
"action": "quarantine",
"field_path": "$.payload.amount",
"message": "Expected number but received string."
}
],
"validated_at": "2026-06-25T10:41:14Z"
}
16. Runtime Configuration
validation:
engine:
meid: MEID_SIGNAL_VALIDATE_STRUCTURE
cmi: vera.TG-VALIDATE.ENGINE.STRUCTURE.1_0_0
rule_loading:
source: zar.validation_rule_registry
only_active: true
include_experimental: false
evaluation:
stop_on_abort: true
accumulate_failures: true
max_failures: 50
actions:
missing_required_field: quarantine
invalid_eco_number: abort
invalid_did: reject
invalid_signature: reject
invalid_unit: quarantine
replay:
record_rule_trace: true
include_rule_versions: true
dal:
anchor_validation_summary: true
anchor_failure_hashes: true
17. API Specification
17.1. Endpoint
POST /api/trustgate/MEID_SIGNAL_VALIDATE_STRUCTURE
17.2. Request
{
"signal": {
"signal_id": "SIG-2026-00001472",
"eco_number": "ECO-A123",
"csi": "comp.TG.INPUT.PARSED-SIGNAL.v1_0",
"payload_type": "invoice",
"payload": {}
},
"validation_profile": "trustgate.default.v1"
}
17.3. Successful Response
{
"status": "passed",
"validation_id": "VAL-2026-000442",
"final_action": "pass",
"rules_checked": 42,
"rules_failed": 0
}
17.4. Failed Response
{
"status": "failed",
"validation_id": "VAL-2026-000443",
"final_action": "quarantine",
"rules_failed": 2
}
18. Runtime Events
18.1. Validation Passed Event
{
"event_type": "trustgate.validation.passed",
"validation_id": "VAL-2026-000442",
"signal_id": "SIG-2026-00001472",
"engine_cmi": "vera.TG-VALIDATE.ENGINE.STRUCTURE.1_0_0",
"rules_checked": 42,
"timestamp": "2026-06-25T10:41:14Z"
}
18.2. Validation Failed Event
{
"event_type": "trustgate.validation.failed",
"validation_id": "VAL-2026-000443",
"signal_id": "SIG-2026-00001473",
"final_action": "quarantine",
"failures": [
"TG-VAL-0002",
"TG-VAL-0011"
],
"timestamp": "2026-06-25T10:41:14Z"
}
18.3. Rule Trace Event
{
"event_type": "trustgate.validation.rule_trace",
"validation_id": "VAL-2026-000443",
"rule_code": "TG-VAL-0011",
"result": "failed",
"field_path": "$.payload.amount",
"duration_ms": 3
}
19. DAL Integration
The Structure Validation Engine prepares validation artifacts for DAL anchoring.
DAL anchor candidates include:
- validation summary hash;
- failed rule hash;
- CSI version hash;
- rule registry version hash;
- input payload hash;
- output validation result hash.
Example:
{
"artifact_type": "TrustGateValidationResult",
"artifact_hash": "sha256:7a9f...",
"engine_cmi": "vera.TG-VALIDATE.ENGINE.STRUCTURE.1_0_0",
"meid": "MEID_SIGNAL_VALIDATE_STRUCTURE",
"signal_id": "SIG-2026-00001472",
"validation_id": "VAL-2026-000442"
}
The engine does not directly finalize the DAL ledger entry. Final anchoring is handled by the TrustGate DAL Anchor Engine.
20. Replay Behaviour
The engine is natively replayable.
Replay requires:
| Replay Input | Description |
|---|---|
| Parsed signal payload | Original parsed signal. |
| CSI contract version | Exact schema used at validation time. |
| Validation rule set | Rule IDs and versions evaluated. |
| Runtime configuration | Action resolution configuration. |
| Engine CMI | Exact validator implementation. |
Replay passes when:
original_validation_result_hash == replay_validation_result_hash
Replay failure indicates one of:
- schema drift;
- rule drift;
- configuration drift;
- engine drift;
- non-deterministic validation behavior;
- corrupted input artifact.
21. Federation Behaviour
The engine is federation-aware.
Federated validation is required when payloads originate from, or are exchanged with, another ECO node.
Federation-specific checks include:
| Check | Rule |
|---|---|
| ECO Number resolvable | TG-VAL-0008 |
| DID valid | TG-VAL-0009 |
| Signature valid | TG-VAL-0010 |
| CSI version supported | TG-VAL-0004 |
| CMI reference active | TG-VAL-0005 |
| Federation node eligible | Future federation rule |
A federated validation result may be exported through AFLE as assurance metadata.
22. Security Model
The engine handles potentially untrusted input and therefore operates in a strict zero-trust mode.
Security controls include:
- schema allowlisting;
- payload size limits;
- JSON parser hardening;
- signature verification;
- DID verification;
- strict datatype validation;
- rule sandboxing;
- no dynamic code execution from payloads;
- rule expression execution in isolated evaluator;
- audit logging for every validation result.
23. Failure Handling
| Failure Type | Default Action |
|---|---|
| Invalid JSON | Reject |
| Missing required field | Quarantine |
| Invalid datatype | Quarantine |
| Unknown CSI | Quarantine |
| Unsupported CSI version | Quarantine |
| Invalid CMI | Reject |
| Unknown ECO Number | Abort |
| Invalid DID | Reject |
| Signature failure | Reject |
| Rule registry unavailable | Abort |
| SSSR unavailable | Abort |
The engine must never forward a failed payload to the Signal Normalizer unless the final action is warn or review and the active policy explicitly permits continuation.
24. Observability Metrics
| Metric | Description |
|---|---|
trustgate_validation_total | Total validation executions. |
trustgate_validation_passed_total | Successful validations. |
trustgate_validation_failed_total | Failed validations. |
trustgate_validation_quarantine_total | Payloads routed to quarantine. |
trustgate_validation_abort_total | Payloads aborted due to critical failures. |
trustgate_validation_latency_ms | Validation latency. |
trustgate_validation_rule_failures_total | Rule-level failures. |
trustgate_validation_rule_latency_ms | Per-rule execution time. |
trustgate_validation_schema_cache_hit_ratio | Schema cache efficiency. |
trustgate_validation_registry_lookup_failures_total | ZAR/SSSR lookup failures. |
These metrics feed VIZZ, AAE, TrustGate operations, and assurance dashboards.
25. Performance Targets
| Metric | Target |
|---|---|
| Average validation latency | < 25 ms |
| P95 validation latency | < 75 ms |
| P99 validation latency | < 150 ms |
| Throughput per worker | 5,000 validations/sec |
| Rule evaluation determinism | 100% |
| Replay consistency | 100% |
| Availability | 99.99% |
| Schema cache hit ratio | > 95% |
26. Testing Requirements
Every implementation must include:
- valid payload fixtures;
- invalid JSON fixtures;
- missing-field fixtures;
- invalid datatype fixtures;
- invalid CSI fixtures;
- invalid CMI fixtures;
- invalid ECO Number fixtures;
- invalid DID fixtures;
- failed signature fixtures;
- replay equality tests;
- rule ordering tests;
- action precedence tests.
A build must fail if validation fixtures do not produce the expected rule codes.
27. Compliance Contribution
| Framework | Contribution |
|---|---|
| CSRD | Data quality and evidence traceability. |
| ESRS | Disclosure data quality and uncertainty support. |
| ISO 14064-1 | GHG data integrity and verification support. |
| ISO 27001 | Runtime input control and security validation. |
| EU AI Act | AI-related payload validation and traceability. |
| W3C DID | Identity verification for federated payloads. |
| W3C VC | Signature and credential validation support. |
28. Developer Notes
Developers implementing this engine must:
- load validation rules from ZAR, not hardcode rule behavior;
- use CSI and SSSR contracts as the source of truth;
- return canonical rule codes for every failure;
- preserve deterministic rule ordering;
- ensure every validation decision is replay-safe;
- hash input and output payloads using canonical JSON serialization;
- never mutate the parsed input object;
- emit rule trace events when replay mode is active;
- fail closed if rule registries or mandatory schemas are unavailable.
29. Summary
The TrustGate Structure Validation Engine provides the platform-wide validation layer for canonical TrustGate signals.
It is the first formal assurance checkpoint after parsing and ensures that all downstream TrustGate engines receive structurally valid, registry-compliant, replay-safe, and federation-compatible runtime objects.
By using the ZAR validation rule registry and controlled validation vocabularies, this engine establishes a reusable validation framework that can be extended across the full ZAYAZ platform.