Skip to main content

Language Syntax

This page outlines the core structural syntax and declaration forms used throughout the Scapius DSL.

1. Entity Declarations​

Entities are defined using an entity keyword, a unique snake_case identifier, a quoted display name, and an optional body block:

<entity_keyword> <entity_id> "<Display Name>" {
    <property_declarations>
    <nested_blocks>
    <inline_child_entities>
    <relationship_blocks>
}

Example​

system core_banking "Core Banking Platform" {
    description "Central account and ledger processing engine"
    tier "Tier-1"
    status "Active"
}

2. Property Declarations​

Properties configure the metadata, metrics, and behavioral properties of an entity.

Built-in Scalar Properties​

// String properties
description "End-to-end customer checkout"
owner "Retail Architecture Team"
version "2.4.1"

// Boolean properties
internet_facing true
is_external false
pii true

// Numeric properties
probability 0.05
cvss_score 9.8
business_value 8

Enumeration Properties​

Many properties accept strictly typed enum literals (string-based):

time "Invest"            // "Tolerate" | "Invest" | "Migrate" | "Eliminate"
risk "High"                // "High" | "Medium" | "Low"
criticality "Mission-Critical" // "Mission-Critical" | "Business-Critical" | "Operational" | "Administrative" | "Standard"
classification "Confidential"  // "Public" | "Internal" | "Confidential" | "Restricted"

Array Properties​

tags ["core", "pci", "cloud-native"]

3. Special Complex Blocks​

Scapius includes dedicated blocks for multi-attribute structures such as lifecycles, assessment scores, and security classifications:

lifecycle Block​

lifecycle {
    phase Run start "2023-01-15" end "2026-12-31"    // Single-line format (preferred)
}

score Block (TIME / Strategy Assessment)​

score {
    business_value 9       // 1 to 10
    tech_fit 8             // 1 to 10
}

security Block (CIA Triad)​

security {
    confidentiality High   // Low | Medium | High | Critical
    integrity High
    availability Critical
}

cost Declaration (Shorthand & Block)​

// Shorthand
cost 25000 month

// Block form
cost {
    amount 25000
    unit month
}

4. Custom Attributes (attr)​

Custom attributes can be applied to any entity or relationship:

attr cloud:region "us-east-1"
attr finops:cost_center "FIN-802"
attr sec:data_owner "Chief Risk Officer"

5. Relationship Declarations​

Relationships connect two entities via one of the 16 supported verbs (composed_of, realizes, serves, hosts, reads, writes, flows_to, triggers, influences, migrates_to, depends_on, governed_by, mitigates, protects, targets, encloses):

Form A: Entity Block Form (relationships { ... })​

Recommended inside entity declarations. The keyword this automatically refers to the parent entity:

system payment_hub "Payment Hub" {
    relationships {
        this reads customer_db "Reads customer records"
        this writes transaction_log "Writes ledger transactions"
        this governed_by pci_policy "Enforces PCI DSS" { status "Compliant" }
    }
}

Form B: Global Relationship Form​

Declared at the top level or within layer blocks:

payment_hub flows_to analytics_engine "Streams CDC events" {
    cardinality OneToMany
    tags ["realtime", "kafka"]
}

6. View Declarations & Text Annotations​

Views project architecture subsets and support inclusion/exclusion filters, verb filters, layout directives, view-level metadata (description, owner, tags, attr), and markdown text annotations:

views {
    landscape core_landscape "Core Architecture Landscape" {
        description "Primary enterprise architecture overview"
        owner "Architecture Guild"
        tags ["core", "landscape"]
        attr review_status "Approved"

        include *
        exclude where layer == "Security Layer"
        auto_layout TopToBottom

        text migrationNote """
            Payments platform migration in progress -
            see ADR-0042 for target-state rationale.
        """ {
            anchor payment_hub
        }
    }
}

7. Style Rules & View Data Elements​

Visual styling can be defined globally in a root styles { ... } block or scoped inside individual view declarations.

Structural Selectors​

Target entity kinds, relationship verbs, or wildcard elements:

styles {
    style system {
        shape "rounded_rectangle"
        background "#1e293b"
        border "#3b82f6"
    }

    style app where tier == "Tier-1" {
        border "#ef4444"
        border_width 3
    }

    style flows_to {
        stroke "#60a5fa"
        stroke_style "dashed"
    }
}

Data Element Selectors (phase.* and time.*)​

Data elements within specialized views (lifecycle_roadmap bars and portfolio_matrix points/quadrants) use dotted selectors:

// Workspace-level or in-view style rules:
styles {
    // Override lifecycle roadmap phase bars
    style phase.Plan {
        fill "#94a3b8"
    }
    style phase.Run {
        fill "#10b981"
        stroke "#059669"
    }

    // Override portfolio matrix TIME points and quadrant tints
    style time.Invest {
        fill "#3b82f6"
    }
    style time.Eliminate {
        fill "#ef4444"
        opacity 0.9
    }
}

In-View Style Scoping​

In specialized views like lifecycle_roadmap or portfolio_matrix, style rules can be scoped directly inside the view definition to override global defaults:

views {
    portfolio_matrix CloudModernization "Cloud Modernization Matrix" {
        include app
        // Scoped style rule for this view only
        style time.Invest {
            fill "#059669"
        }
    }
}

Owning Entity Predicates​

Data element rules can specify conditions based on the owning entity's attributes (e.g. criticality, tier, owner):

style phase.Run where criticality == "Mission-Critical" {
    fill "#15803d"
    border "#166534"
}

Next Steps​