AAL language reference
Reference AAL identifiers, metadata, object colors, hierarchy rules, and reserved keywords for valid architecture-as-code models.
Acefy Architecture Language (AAL) · AAL C4 0.2 · Level-aware semantics

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:
Optional visual override from the shared icon registry; never changes semantic type. Omit for Automatic.
container Db "Database" database { icon "brand/postgresql" }A human-readable explanation of the element or relationship.
description "Customer banking application"The primary technology or framework used. Technology is metadata, not structure.
technology "Java / Spring Boot"The team or person responsible for this element.
owner "Platform Team"Comma-separated string labels for categorization. Use tags for additional characteristics beyond the primary semantic type.
tags "critical", "sync"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, slate, silver, charcoal, stone, brown, chocolate, sand, peach, coral, burgundy, salmon, mint, emerald, olive, sky, navy, lavender.
container API "Customer API" api {
color blue
}Marks a system as external to the organization. Optionally followed by a System-level semantic type. Rendered with a dashed border.
system Okta "Okta" external identityThe 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.
protocol httpsThe 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.
mode synchronousObject 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.
container API "Customer API" api {
color blue
}Supported color tokens (33 total):
Valid Hierarchy
AAL enforces a strict C4 hierarchy with level-aware semantic validation:
├── Person
└── Software System (System semantics)
└── Container (Container semantics)
└── Component (Component semantics)
person Customer "Customer"system Platform "Platform"system Platform {
container API "API"
}container API {
component Auth "Auth"
}system Okta "Okta" external identitycomponent PolicyRepository "Policy Repository" repositorysystem Platform {
component Auth "Auth"
}component DB "Database" databasesystem LoginController "Login Controller" controllerReserved Keywords
The following keywords cannot be used as element identifiers (375 total):