Relationship Syntax

Scapius supports two distinct forms for declaring relationships between entities: the Entity Block Form and the Global Form.

---

1. Entity Block Form (relationships { ... })

This is the recommended pattern. When declared inside an entity, the keyword this automatically resolves to the enclosing entity:

system sys_payment "Payment Gateway" {
    relationships {
        this reads data_customer "Reads user profile"
        this writes data_ledger "Persists transaction state"
        this depends_on sys_auth "Validates bearer tokens"
    }
}

Explicit Source References Inside Blocks

You can also declare relationships between child entities inside an entity's relationships block:

system sys_payment "Payment Gateway" {
    app app_api "Payment API" { }
    agent ai_fraud "Fraud Agent" { }

    relationships {
        ai_fraud protects app_api "Monitors request stream" {
            mechanism "Monitoring"
        }
    }
}

---

2. Global Form

Relationships can be declared globally at the workspace root or inside layer and group blocks:

# Syntax: <source_id> <verb> <target_id> "<optional_label>"? ({ <properties> })?
sys_payment flows_to sys_analytics "Streams telemetry events"

---

3. Relationship Property Blocks { ... }

You can attach detailed architectural metadata to any relationship statement using a trailing property block:

this governed_by pol_pci_dss "Enforces card data protection" {
    status "Compliant"
    cardinality OneToMany
    tags ["pci", "audit-2026"]
    description "Validated during annual QSA audit"
    attr sec:reviewer "External Auditor"
}

Supported Relationship Properties

Property	Type	Description
label	string (quoted)	Short display label displayed along the edge on diagram views
status	string	e.g. "Compliant", "Non-Compliant", "Proposed", "Deprecated"
cardinality	enum	OneToOne, OneToMany, ManyToMany
interface_type	string	e.g. "REST", "gRPC", "Kafka", "CDC"
mechanism	string	e.g. "Authentication", "Encryption", "Monitoring", "Access Control"
description	string	Extended narrative explaining the technical integration
tags	string[]	Array of search / filter tags
attr	Custom attributes	Namespaced key-value pairs (e.g. attr net:port "443")

---

4. Disallowed Relationships & Validation

Scapius compiler verifies relationships at build time. Declaring an invalid verb between incompatible source and target entities raises a semantic error:

# ❌ Error: An actor cannot compose a database
actor user_admin "System Admin" {
    relationships {
        this composed_of infra_db  # Compiler Error!
    }
}