Documentation and rationale for the Audit-by-Design DSL Explains the principles, design decisions, and use cases of the domain-specific language for defining, validating, and auditing atomic requirements (AFOs) in regulated software systems.
We are developing a domain-specific language (DSL) that enables the atomization, validation, and traceability of requirements (AFOs) in regulated software systems and above.
Here you'll find all docs and further instruction how to find all other information necessary: ├── README.md
This language is designed to:
- be human- and machine-readable (structured text or JSON),
- represent syntactically unambiguous and verifiable requirements,
- be testable, versionable, and auditable (via Git integration),
- support automatic validation and auditing (CI/CD),
- and semantically represent governance rules, negative rules, and exclusions.
##Design Principles
| No. | Principle | Description |
|---|---|---|
| 1 | Human readability | Text structure and indentation must be visually logical. |
| 2 | Machine validation | Unambiguous grammar and reserved keywords. |
| 3 | Parser-friendly grammar | Formally defined, context-free (CFG-based). |
| 4 | Extensibility | Syntax and semantics are modular and adaptable. |
| 5 | Toolchain integration | Integrated with Git, CI/CD, and audit pipelines. |
| 6 | Java-free implementation | Focus on Deno/TypeScript or Rust environments. |
| 7 | Rule-based prohibitions | “Must not” and “May not” constructs for governance. |
| 8 | Central traceability | Full audit trail and traceability of all rule changes. |
👉 01_DSL_Goals_and_Principles.md
for more details on motivation, goal setting, and design principles.
Digital transformation in regulated environments has reached a critical point.
Many public digitalization projects in Germany and Europe have demonstrated the limits of fragmented, incompatible, and non-auditable infrastructures — both technically and in terms of public trust and acceptance.
Following Auguste Kerkhoffs’ principle — that security must rely on transparent, verifiable systems rather than obscurity — this project applies the same logic to requirements engineering. Software systems that govern public or regulated domains must be traceable, testable, and independently auditable from the first requirement onward.
The current practice of describing requirements in natural language or heterogeneous formats creates ambiguity and prevents automated validation.
A domain-specific language (DSL) addresses this by providing:
- Formal precision – each requirement becomes a deterministic, testable atom.
- Auditability by design – syntax and semantics enforce verifiability.
- Human and machine readability – bridging expert review and automation.
- Governance integration – embedding rule types, constraints, and exclusions.
Our DSL defines the atomic unit of trust:
a requirement that can be understood, verified, versioned, and audited — without depending on specific platforms or vendor interests.
True digital sovereignty does not come from building yet another isolated infrastructure but from making existing ones transparent and auditable.
Instead of debating shortcomings, this initiative proposes a constructive, consensus-oriented approach that:
- enables voluntary participation and self-determined data control,
- fosters interoperability through open, standard-based semantics, and
- ensures that every rule, validation, and exception remains inspectable.
In essence, trust arises from transparency, and transparency begins with the language we use to define what systems must — and must not — do.
The Audit-by-Design DSL is actually divided into two core repositories —
one for concept and specification, and one for implementation and validation.
| Repository | Purpose | Access |
|---|---|---|
rock-the-prototype/dsl-docs |
Documentation, principles, grammar, and design rationale | You are here ✅ |
rock-the-prototype/dsl-core |
Core specification and schemas for machine validation and parser integration | Open Repository → |
Start here in dsl-docs to understand:
- the motivation and guiding principles (01_DSL_Goals_and_Principles.md),
- the formal grammar definition (02_DSL_Grammar.md),
- and how validation and auditability are built into secure design.
These documents explain why the DSL exists, how it is structured,
and which principles ensure auditability, transparency, and regulatory alignment.
Once you understand the conceptual foundation,
visit dsl-core to see how the DSL is implemented.
There you’ll find:
- the current JSON schemas and validation logic,
- examples of atomic requirement definitions,
- and the integration points for CI/CD validation pipelines.
The dsl-core repository is where machine-readable trust begins —
it provides the structural backbone for any parser, validator, or compliance framework built on top of this DSL.
The DSL is open for participation.
Whether you are a developer, architect, researcher, or compliance expert —
your contributions help make requirements transparent, testable, and verifiable for everyone.
If you’d like to join, please see
👉 How to Contribute (coming soon)
for details on collaboration, governance rules, and peer review.
❇️ Audit-by-Design is not just a concept — it is an invitation to co-create a transparent, verifiable foundation for digital trust. ❇️ Every contribution strengthens the collective ability to build software that is explainable, compliant, and accountable by secure design. ❇️
By contributing to the Audit-by-Design DSL initiative, organizations gain tangible and strategic advantages:
-
Verifiable compliance
Each requirement can be linked to audit rules and legal references (e.g. AFOs, BSI TRs, EUDI).
This reduces audit effort, supports conformity checks, and shortens certification cycles. -
Traceable development processes
The DSL integrates directly with Git-based workflows, enabling continuous validation and historical traceability of all requirement changes. -
Improved software assurance
Formalized requirements reduce ambiguity in specifications and vendor contracts.
Testing and validation become reproducible and verifiable. -
Trust and transparency by design
Publicly understandable and machine-readable requirements build confidence
among users, partners, and oversight bodies — not just within IT,
but across management, governance, and compliance departments. -
Cross-sector interoperability
Shared semantics allow organizations from different sectors
to align their audit criteria and technical standards without revealing proprietary data. -
Reduced operational risk
Consistent definitions and automated validation help detect conflicts,
redundancies, and gaps early — before they manifest in production or compliance audits. -
Sovereignty through open standards
Participation ensures independence from proprietary toolchains
and strengthens collective control over digital trust infrastructures.
In short: Organizations that contribute to the DSL are shaping the standard
for trustworthy digital services — not adapting secure design to it later.
│ │
│
├── 02_DSL_Grammar.md
the formal grammar definition (02_DSL_Grammar.md),syntax principles, and examples
Defines the smallest atomic unit of the Audit-by-Design DSL —
a Requirement Atom — based on a deterministic, context-free grammar (CFG).
The Audit-by-Design DSL uses a context-free grammar (CFG) to describe
the smallest verifiable unit of a requirement — the Requirement Atom.
This grammar defines how human-readable statements can be parsed into
machine-interpretable structures for validation, testing, and audit reporting.
<requirement> ::= <sentence> <terminator>
<sentence> ::= <actor_clause> <action_clause> [<condition_clause>] [<result_clause>]
<actor_clause> ::= "As" <role>
<action_clause> ::= "I" <modality> <action>
<condition_clause> ::= "when" <condition>
<result_clause> ::= "then" <expected_result>
<terminator> ::= "."
<modality> ::= "must" | "must not"
<role> ::= <identifier>
<action> ::= <verb_phrase>
<condition> ::= <clause>
<expected_result> ::= <clause>
<identifier> ::= [A-Za-z0-9_-]+
<verb_phrase> ::= [A-Za-z ]+
<clause> ::= [A-Za-z0-9 ,_()-]+“As a system,
I must validate the access token
when receiving an ePrescription request
then log success or failure.”
In regulated environments, every software action that processes, stores,
or transmits data must be traceable, verifiable, and reproducible.
That is the essence of Secure by Design and Audit by Design.
The Audit-by-Design DSL ensures that such requirements are written
in a form that is unambiguous, testable, and machine-validated.
Even a simple statement like the following demonstrates how
security, compliance, and auditability are expressed in one atomic sentence.
The Audit-by-Design DSL restricts modalities to a binary logic
in order to maintain full determinism and auditability.
Rationale
Only binary modalities can be deterministically evaluated — either a condition is fulfilled or it is violated. Anything else (e.g., “should” or “may”) would introduce uncertainty and therefore be non-deterministic, making it unsuitable for CI/CD validation and automated compliance checks.
This strict modality model ensures traceability and verification in continuous audit pipelines, where every rule must yield a reproducible result: pass or fail.
Alignment with RFC 2119
This decision aligns with the IETF RFC 2119
standard for normative language in technical specifications, which defines:
MUST / MUST NOT – absolute requirements of the specification
SHOULD / MAY – optional or recommended behavior, not mandatory
By limiting the DSL to “must” and “must not”, we preserve semantic precision, regulatory coherence, and machine verifiability — all essential pillars of SECURE Audit-by-Design.
│ │
│
├── 03_Validation_and_Audit.md
├── 04_Examples.md
│
│
├── 05_Governance_and_Rules.md
│
│
│
└── assets/
├── diagrams/
│ └── dsl-cfg-structure.png
# later CFG graphic
└── examples/
└── requirement_atom.json
# JSON example for reference
The **Audit-by-Design DSL Docs ** are released under
Creative Commons Attribution 4.0 International License (CC BY 4.0).
© 2025 Sascha Block / Rock the Prototype