AAL language reference

Reference AAL identifiers, metadata, object colors, hierarchy rules, and reserved keywords for valid architecture-as-code models.

AAL C4 v0.2 — Level-Aware Semantics

Use C4 AI Instructions with an external AI assistant, then copy its generated AAL into a new C4 Architecture project. Inspect diagnostics and explicitly Save.

Independent project copies

Use Clone to cloud or Clone to local from a project card’s menu. The copy includes the last saved source and layout; future changes do not sync. Duplicate keeps the same location. Cloning is available only on the Projects page. At three cloud projects, delete one to make room; existing cloud projects can still be saved.

Identifiers

IDs must be unique across the entire architecture.
IDs cannot contain spaces.
IDs should begin with a letter.
PascalCase is recommended (e.g. CustomerProfileAPI).
IDs are separate from display names. The ID is the identifier; the name is the label.
IDs cannot be reserved keywords (see Reserved Keywords).

Metadata Fields

AAL supports the following metadata fields across elements and relationships:

description

Elements & Relationships

A human-readable explanation of the element or relationship.

Example

description "Customer banking application"

technology

Systems, Containers, Components, Relationships

The primary technology or framework used. Technology is metadata, not structure.

Example

technology "Java / Spring Boot"

owner

Systems, Containers, Components

The team or person responsible for this element.

Example

owner "Platform Team"

tags

Elements & Relationships

Comma-separated string labels for categorization. Use tags for additional characteristics beyond the primary semantic type.

Example

tags "critical", "sync"

color

Systems, Containers, Components, Persons

Author-controlled visual classification using a curated pastel palette. Color is AAL metadata — it does not replace semantic type or structural identity. Supported values: default, gray, blue, cyan, teal, green, lime, yellow, amber, orange, red, rose, pink, purple, violet, indigo.

Example

container API "Customer API" api {
    color blue
}

external

Systems

Marks a system as external to the organization. Optionally followed by a System-level semantic type. Rendered with a dashed border.

Example

system Okta "Okta" external identity

protocol

Relationships

The communication protocol used in the relationship. Protocol is a controlled vocabulary — it is not free text. Values are matched case-insensitively and canonicalized to lowercase. Supported values: http, https, rest, graphql, grpc, grpc-web, graphql-subscription, soap, jsonrpc, xmlrpc, thrift, webhook, openapi, websocket, sse, webrtc, mqtt, coap, amqp, jms, stomp, nats, kafka, pulsar, redis-pubsub, ftp, sftp, ftps, as2, as4, scp, jdbc, odbc, sql, postgres, mysql, mongo, redis, cassandra, smtp, imap, pop3, ews, ldap, ldaps, oauth2, oidc, saml, kerberos, scim, mcp, a2a, lsp, openai-api, anthropic-api, opc-ua, modbus, dds, can, bacnet, hl7, fhir, fix, swift, iso8583, edi, x12, edifact, corba, dcom, rmi, ejb, tcp, udp, tls.

Example

protocol https

mode

Relationships

The semantic interaction mode. Supported values: synchronous, asynchronous, event, stream, batch, file, tool (AI tool-call), a2a (agent-to-agent), realtime (WebSocket/SSE/WebRTC). Mode describes architecture semantics — it is independent of visual edge style (Orthogonal/Curved/Straight). Relationship modes are level-independent: they may be used between Systems, Containers, or Components.

Example

mode synchronous

Object Color

AAL supports an optional color metadata field for visual classification using a curated pastel palette. Color is AAL metadata — it does not replace semantic type or structural identity.

Example

container API "Customer API" api {
    color blue
}

Supported color tokens (16 total):

default

gray

blue

cyan

teal

green

lime

yellow

amber

orange

red

rose

pink

purple

violet

indigo

Design Rule: Color is an additional visual classification. It does not replace the semantic type, structural identity, or icon. All text remains dark for readability over pastel backgrounds. Unknown color values produce a validation error.

AAL vs View Layout Metadata: AAL contains hierarchy, structural types, semantic types, description, technology, owner, tags, color, and relationships. View Layout Metadata contains node positions, group dimensions, edge style, source/target attachment sides, label positions, and canvas settings. Connection attachment sides are NOT AAL.

Valid Hierarchy

AAL enforces a strict C4 hierarchy with level-aware semantic validation:

Architecture
├── Person
└── Software System (System semantics)
└── Container (Container semantics)
└── Component (Component semantics)

Valid

Persons are top-level.

Example

person Customer "Customer"

Valid

Systems are top-level.

Example

system Platform "Platform"

Valid

Containers belong inside Systems.

Example

system Platform {
    container API "API"
}

Valid

Components belong inside Containers.

Example

container API {
    component Auth "Auth"
}

Valid

External systems may carry a System-level semantic type after "external".

Example

system Okta "Okta" external identity

Valid

Components may carry a Component-level semantic type.

Example

component PolicyRepository "Policy Repository" repository

Invalid

Components cannot belong directly to Systems — they must be inside a Container.

Example

system Platform {
    component Auth "Auth"
}

Invalid

"database" is a Container semantic type, not a Component semantic type.

Example

component DB "Database" database

Invalid

"controller" is a Component semantic type, not a System semantic type.

Example

system LoginController "Login Controller" controller

Reserved Keywords

The following keywords cannot be used as element identifiers (375 total):

architecture

person

system

container

component

external

description

technology

owner