Declarative Capability Language
Describe software systems by what they mean.
DCL treats capabilities as architecture: the missing unit between business intent, system design, and software delivery.
It is an experimental declarative language for preserving capability meaning as explicit, inspectable, and compiler-verifiable system semantics.
DCL v0.9 ยท Status: Experimental
Why DCL exists
Software delivery is full of translation. Business strategy becomes initiatives. Initiatives become architecture. Architecture becomes services, APIs, queues, workflows, tickets, and code.
But the capability itself, the responsibility the business actually needs the system to provide, is rarely preserved as a first-class artefact. DCL exists to make that capability explicit.
DCL is for the architectural meaning that gets lost between strategy and code.
- What responsibility does this system expose?
- What intent can ask for it?
- What outcomes can result?
- What rules and policies govern it?
- What effects and events does it cause?
- How does it progress over time?
The translation gap
Today, capability meaning is often implicit, spread across diagrams, tickets, prose, service boundaries, and implementation code. DCL places capability explicitly in the middle as a language-level representation of business responsibility, intent, outcomes, effects, policies, and lifecycle progression.
What DCL changes
A capability becomes a first-class language construct, not a paragraph in a document or a hidden assumption inside a service.
DCL models meaningful results, including rejection, failure, deferral, and partial completion.
Persistence, publication, notification, invocation, and other side effects become part of the declared model.
Reliability, security, observability, and governance are attached to language elements instead of being buried in middleware or infrastructure.
Long-running behaviour is described as business progression, not just workflow plumbing.
The compiler can validate references, ambiguity, lifecycle structure, policy attachment, and semantic completeness.
Problems DCL addresses
The original business capability is often diluted as it moves from strategy to architecture to code.
Teams often model endpoints, services, queues, handlers, and database tables before modelling the responsibility the system exposes.
Architecture documents and diagrams help humans, but they cannot usually be compiled, analysed, or checked for ambiguity.
Retries, timeouts, observability, authorisation, and reliability rules are often scattered across code and platform configuration.
AI tools work better with structured, explicit, compiler-checkable context than with loose prose, stale diagrams, and fragmented implementation details.
What is DCL?
DCL is a declarative capability language. Instead of starting with endpoints, services, queues, or controllers, DCL starts with the responsibility a system exposes: the capability, the intent it accepts, the outcomes it can produce, and the rules that keep those outcomes meaningful.
Existing programming languages model implementation well, but they do not model business intent directly. Existing architecture diagrams and documents describe systems, but they are not compiler-verifiable. DCL describes what software means before describing how it is implemented.
DCL v0.9 is experimental. The current website includes learning pages, guides, validated examples, and a browser playground with compiler feedback and model visualisations. Editor integrations, language server support, MCP tooling, and production runtime projections remain future work.
Use DCL where you work
The playground is the best place to learn DCL concepts quickly. The VS Code extension is the workbench for editing real `.dcl` files, running compiler diagnostics with the bundled compiler, navigating the DCL Explorer, and opening semantic graphs from your workspace.
Marketplace publishing is planned. For now, install the extension from a VSIX package.
Latest VSIX: dcl-vscode-extension-v0.4.3.vsix. If the latest
release asset is not attached yet, use the GitHub Actions artifact link.
- Download the VSIX file.
- In VS Code, run
Extensions: Install from VSIX.... - Select the downloaded
.vsix. - Reload VS Code when prompted.
- Run
DCL: Show Compiler Infoif you need to inspect the bundled compiler.
Language Concepts
System responsibilities described as language primitives.
The input or request a capability is designed to handle.
Named results that make success, refusal, and deferral explicit.
Invariants and decision constraints that shape valid behavior.
Observable changes a capability may cause.
Signals emitted or awaited by capabilities and lifecycles.
Operational and architectural requirements attached to language elements.
Progression through states, outcomes, events, and completion.
A small DCL example
This example sketches a customer registration capability. It names the intent, outcomes, rules, effects, emitted events, and outcome selection without prescribing a service framework or runtime implementation.
language dcl 0.9
actor Customer is human
effect PersistRegistration is persistence
effect SendVerificationMessage is notification
shape RegistrationInput {
email: Email required
acceptedTerms: Boolean required
}
event VerificationMessageSent is {
email: Email required
}
capability RegisterCustomer {
intent RegistrationInput from Customer
outcomes {
RegistrationAccepted
TermsRejected
VerificationDeferred
}
rule TermsAccepted: input.acceptedTerms is true
effects {
PersistRegistration
SendVerificationMessage after PersistRegistration
}
events {
emits VerificationMessageSent
}
when {
TermsAccepted violated then TermsRejected
SendVerificationMessage unresolved then VerificationDeferred
otherwise then RegistrationAccepted
}
}
Keep exploring
DCL is not infrastructure-as-code, just documentation, or a framework convention. It is a language for expressing what a system is responsible for, what intent it accepts, what outcomes it can produce, what it causes, and what policies govern it.