earslang
A language for writing software requirements that leave less to guess than prose: each one says when it applies, what it applies to, and how strictly. It is plain text, and a free tool checks it.
Requirements written as ordinary prose leave out conditions, mix "should" with "must", and put several duties in one sentence, so the people and AI agents who build from them have to guess. earslang writes each requirement as one sentence in a bulleted list, in a fixed pattern. It is for anyone who writes or signs off requirements, product managers, business analysts and project managers as well as engineers. It needs no programming: the playground checks rules in the browser.
It builds on two published standards: EARS for the sentence patterns, and BCP 14 for the meanings of MUST, SHOULD and MAY.
Open the playground Read the specification
earslang 0.1: every part may still change.
- R1: The app MUST work with no account and no sign-in.
- R2: WHEN the user closes a file, THEN the app MUST ask before discarding changes.
- R3: WHILE offline, THEN the app SHOULD queue every change.
- R4: IF the disk is full, THEN the app MUST warn the user. [proposed]
Each rule is checked. For example, a WHEN with no THEN fails:
- WHEN the user saves, the app MUST write the file.Before and after
A requirement as it is often written:
The app should let users work offline, keep their changes and warn them if there is a problem.
Is "should" a must or a wish? Kept until when? What problem? And three duties share one sentence, so none can be signed off alone. The writer answers those questions, and earslang gives each duty a rule of its own:
- R1: WHILE offline, THEN the app MUST let the user keep editing.
- R2: WHILE offline, THEN the app MUST keep every change until it is sent.
- R3: IF a kept change fails to send, THEN the app MUST warn the user.MUST means required, SHOULD recommended and MAY optional. WHERE, WHILE, WHEN and IF say when a rule applies; after them, THEN comes before what the rule applies to. Each rule can be tested and cited by its ID.
What earslang is
EARS is the Easy Approach to Requirements Syntax (Mavin et al., 2009). BCP 14 is RFC 2119 and RFC 8174, which internet standards use for these words.
Patterns
EARS gives five sentence patterns that read the same way every time: what must hold, when, and for which system. They are ubiquitous (always), state (WHILE), event (WHEN), optional feature (WHERE) and unwanted event (IF). earslang keeps them, writes the structure words in capitals, and puts THEN after the conditions, before the system.
Strength
The BCP 14 keywords give a rule its strength: MUST, MUST NOT, SHOULD, SHOULD NOT and MAY; SHALL, REQUIRED and the other BCP 14 words also work. One keyword per rule, so every duty can be tested on its own.
Checks
The compiler checks each rule's structure and ID, the tags that cite other rules, and two rules that say exactly opposite things, such as MUST and MUST NOT with the same words. It writes the rules out as JSON for other tools to read.
Where rules are written
A rule is one sentence of plain text, so it can be kept as written in a Word document, a Confluence page or a Jira ticket. To check rules from there, paste them into the playground one to a line, each starting with a hyphen. The playground runs in your browser and sends nothing to the server, but it keeps the text in the page's address, so the text is in the browser's history and in any link copied from the page. For confidential requirements, check your organisation's policy first, or use the compiler on your own machine. The compiler checks rules in a .ears file, which is markdown, or in an ```ears block in any markdown file. GitHub, GitLab, editors and wikis show these as a readable list, with no plugin. The compiler is optional.
Spec-driven development and AI agents
earslang is a language for writing requirements. Its name is EARS plus "lang": here EARS stands for EARS Amplified by RFC for Spec-Driven Development. In spec-driven development the requirements are written first, and people or AI agents build from them, so a vague requirement turns into a guess in the code. An earslang rule says when it applies, which system it binds, and how strictly, so there is less to guess. The earslang agent skill teaches an AI agent to write earslang; its page says how to install it.
If you know EARS, RFC 2119 or Gherkin
From EARS
The patterns are the same. The condition words are in capitals, and THEN comes once, after all the conditions, not only after IF. Besides shall, you have MUST, SHOULD and MAY. Classic EARS in lowercase is still read: a sentence with one "shall" is valid when a comma or "then" follows its conditions, or when its subject is a system declared in ears.mod. Without any of these, the compiler cannot tell where the subject starts, and says so. With the condition words in capitals, a comma is not enough: THEN is required, unless the system is declared in ears.mod. ears fix rewrites a valid one in the standard form.
- WHEN the user saves, THEN the app MUST write the file.From RFC 2119
The keywords mean what you know. One keyword per rule. Conditions come first, in capitals, then THEN. MAY NOT is refused: use MUST NOT, or MAY with what is allowed.
- The server MUST NOT store passwords in plain text.From Gherkin
Given becomes WHILE for a state, or WHEN for an event; GIVEN is refused. When is WHEN. Then is THEN, followed by the system and a keyword. For And or But between conditions, repeat the condition word: "WHEN a, WHEN b", and name a table (see Two or more conditions). Scenarios stay in Gherkin; ears export --out gherkin writes their skeletons.
- WHILE the cart is empty, THEN the shop MUST refuse payment.Writing rules
A rule is a list item
Write each rule as a list item in a .ears file or an ```ears block. The text around the rules is prose.
The subject is the system, or a part of it
"The app", "the server" and "the preview" are all subjects. A project can list its systems in ears.mod, and the compiler then checks subjects against that list.
"Can" becomes MUST let
Write what the system must do. "The user can export a request" becomes "The app MUST let the user export a request." MAY means the system is free to do it or not, so use it only for that.
- The app MUST let the user export a request.
- The app MAY cache responses.A rule has one duty, and a list can be one duty
"The app MUST export files, history and logs." is one duty if the items are met together. If each can be met or tested on its own, split it into rules. A rule with two keywords is an error; split it. A long list can go in a table, named the same way as the tables below.
An ID ends with a colon and a space
An ID starts with a letter, holds at least one digit, and ends with a colon and a space: R7:, FR-001:, F2.1:, APP-512.1:. IDs are optional. Give one to each rule that others cite. Once one rule in a file has an ID, the compiler warns about a rule without one.
Tags go at the end, after the full stop
[from R7] says a rule comes from R7, and the compiler checks that R7 exists. A rule is in force unless it is tagged [proposed] (not yet agreed) or [dropped] (rejected, kept for the record). A rule can have a [from] tag and one of those two.
- R7: IF a change fails to send, THEN the app MUST NOT lose it.
- R8: The app SHOULD show the next retry time. [from R7] [proposed]Two or more conditions should have a table
Conditions go in the order WHERE, then WHILE, then WHEN or IF, each in capitals, and THEN comes once, after the last. A rule with two or more conditions names a table with [table T1]. The table sits under a heading whose first word is its name, and shows what happens in each case. Without the tag, the compiler warns; with it, the compiler checks that the table is there.
- R5: WHERE sync is on, WHILE offline, WHEN the user saves, THEN the app MUST queue the change. [table T1]
### T1 Saving while offline
| sync | network | the user saves | the app |
|---|---|---|---|
| on | offline | yes | queues the change |
| on | offline | no | does nothing |
| on | online | yes | sends the change |
| on | online | no | does nothing |
| off | offline | yes | keeps the change on the device only |
| off | offline | no | does nothing |
| off | online | yes | keeps the change on the device only |
| off | online | no | does nothing |The playground and ears check run the checks
The playground checks rules in the browser, and says "No problems." when there is no error or warning. On your own machine, ears check (from the download page) prints nothing and exits with status 0 when it finds no problem, and ears export --out json writes the rules as JSON.
Questions
Are there other EARS tools?
Yes. ears-syntax-vscode highlights EARS in VS Code, ears-lint-go checks EARS sentences from Go, and vale-ears checks them with the Vale prose linter. earslang adds the BCP 14 keywords, IDs that other rules cite, tables, an export to JSON and a report of what changed between versions.
Does the playground send my text anywhere?
No. The compiler runs in your browser, and the text stays there: in the page and its address, so also in the browser's history. A share link holds the text itself.