Skip to main content

Semantic Validation Rules & Errors

Scapius compiler executes static semantic verification passes on every .ea model to guarantee architectural integrity. Violations trigger compile-time diagnostics with clear remediation guidance.

1. Global ID Uniqueness​

  • Rule: Every entity ID across the entire workspace must be globally unique, regardless of file boundaries or container nesting.
  • Error Example: 
    [Error NEA2001] Semantic Error: Duplicate view/entity ID 'payment_api' found. All identifiers in the workspace must be globally unique.
  • Remediation: Rename one of the entities using a distinct snake_case suffix (e.g. payment_api_v2 or payment_api_legacy).

2. Single Parent composed_of Rule​

  • Rule: An entity can only be the destination of at most one composed_of relationship. Sub-components cannot be owned by multiple parent systems.
  • Error Example: 
    [Error NEA3004] Linking Error: Target entity 'comp_auth' has multiple composed_of relationships (composed into both 'sys_core' and 'sys_payments'). An entity can only be composed into a single parent entity.
  • Remediation: If multiple systems depend on the module, use depends_on or serves instead of composed_of.

3. Value Stream Stage & Capability Rules​

  • Rule A (order uniqueness): Every stage inside a value_stream with an order property must have a unique integer value.
  • Rule B (Composition Exclusion): composed_of cannot be declared between a stage and a capability.
  • Correct Pattern: Capabilities link to stages using the realizes verb: 
    capability cap_payment "Payment Processing" {
        relationships {
            this realizes stage_checkout "Realizes checkout stage"
        }
    }

4. Lifecycle Date Format & Sequencing​

  • Rule A (Date Sequencing): Dates must conform strictly to "YYYY-MM-DD". If an end date is supplied, it must be chronologically greater than or equal to the start date (NEA4004).
  • Rule B (Linter Style Rule): Phase properties should be declared on a single line: 
    # Preferred single-row format
    phase Run start "2020-01-01" end "2025-12-31"
    Splitting phase, start, and end across multiple lines triggers a linter style warning.

5. Type-Compatible Relationship Rules​

  • Rule: Verbs can only connect entity types permitted in the Master Relationship Matrix.
  • Error Example: 
    [Error NEA3004] Linking Error: Relationship 'actor_user mitigates threat_sql' is invalid. Verb 'mitigates' is not allowed from type 'Actor' to 'Threat'.