earslang 0.1 specification

The specification and its JSON Schemas are under CC BY 4.0 (docs/LICENSE.md). The specification as a markdown file: spec.md.

Reference. This is earslang 0.1, as ears 0.1 implements it. Every command in §11 is built. The md importer and the importers for Kiro, Spec Kit and OpenSpec are experimental (§11.4). Where a part is still open, it says so and names the question in the README.

The normative statements are the rules inside ```ears blocks, the grammar blocks, and the tables that a rule names: Table 7, Table 11.2 and Table 11.5, each numbered by the section that holds it. The rules' keywords are read as BCP 14 (RFC 2119, RFC 8174) describes. The other prose and tables explain and classify; they impose nothing.

Rule IDs are stable; a gap marks a removed rule, and IDs are not reused. Rules mention words, flags and file names in backticks, such as then, --check and ears.mod, because inside a rule only capitals outside backticks and quotes are structure. Sections are cited with §, as in §7.

Blocks marked ```ears,example are examples that must pass the checks. Blocks marked ```ears,compile_fail are examples that must fail them. Both kinds are the conformance suite (§14).


1. What earslang is

earslang is a format for requirements, written in markdown: the sentence patterns of EARS (Mavin et al., 2009) with the keywords of BCP 14, and capitals marking the structure of every sentence. It is written and read mostly without a compiler: in editors, in issue trackers, in merge requests. The compiler, ears, is optional. It checks the format, writes the rules out as JSON with their IDs, links and status, and reports what changed.

A rule is one requirement, written as a list item, or as a paragraph line and the lines joined to it (S4.16, S4.17). A list of rules is a markdown list.

exampleOpen in playground
- R1: The app MUST work with no account and no sign-in.
- R2: WHILE work moves between devices, THEN the app MUST use only what the user already owns.
- The app SHOULD sync in the background.

A classic EARS sentence with one "shall" is valid earslang when a comma or "then" follows its conditions, or its subject is a system declared in ears.mod (S7.4).


2. Where earslang is read

earslang has two containers, and they hold the same text:

The text of a .ears file can be pasted into a block, and back, unchanged. A markdown file keeps its normal name and may hold any number of ears blocks beside any other blocks.

A fenced block is found as CommonMark finds it, so a block inside a list item or a block quote counts, with the list's indentation removed. The language is the info string up to its first space or comma: ```ears,example is an ears block with the attribute example.

Tables are the pipe tables of GitHub Flavored Markdown (GFM), as goldmark's table extension reads them (S19.2), so the compiler reads that extension of CommonMark.

A project is the folder holding an ears.mod file (§3) and everything under it, except a folder that holds its own ears.mod, which is another project. ears.mod is optional: run with no files named and no ears.mod in the folder or above it, the compiler reads the folder it runs in, with the default settings (S2.7).

A pattern such as ./..., the whole project, and the folder the compiler runs in all leave out a folder whose name starts with a dot, such as .github/, and a folder that holds its own ears.mod. A pattern that names such a folder, such as .github/..., reads it.

rulesOpen in playground
- S1.1: WHEN the info string of a fenced code block, up to its first space or comma, is `ears`, THEN the compiler MUST read the block as earslang.
- S1.2: The compiler MUST find fenced code blocks as CommonMark does, including those inside list items and block quotes.
- S1.3: The compiler MUST NOT read an indented code block as earslang.
- S1.4: The compiler MUST read a file whose name ends in `.ears` as it reads the contents of one block.
- S1.5: The compiler MUST NOT read text outside `.ears` files and `ears` blocks as earslang.
- S1.6: WHEN the compiler is given file names, THEN the compiler MUST read those files only.
- S1.7: WHEN the compiler is given a pattern such as `./...`, THEN the compiler MUST read every `.md` and `.ears` file the pattern covers that git does not ignore, except those in a folder under the pattern's folder whose name starts with a dot or that holds its own `ears.mod`.
- S1.8: WHEN the compiler is given no files and no pattern and a project holds the current folder, THEN the compiler MUST read every `.md` and `.ears` file in that project that git does not ignore, except those in a folder whose name starts with a dot.
- S1.9: WHEN the compiler is given no files and no pattern and no project holds the current folder, THEN the compiler MUST read every `.md` and `.ears` file under the current folder that git does not ignore, except those in a folder whose name starts with a dot or that holds its own `ears.mod`.
- S1.10: WHEN a project holds a file, THEN the output MUST give its path relative to the project root, with forward slashes.
- S1.11: The output MUST give the project root relative to the folder the compiler runs in.
- S1.12: WHEN no project holds a file, THEN the output MUST give its path relative to the folder the compiler runs in, with forward slashes.
- S1.13: WHEN a file, `ears.mod` among them, starts with a byte order mark (U+FEFF), THEN the compiler MUST read the file without the mark.
- S1.14: IF a file, `ears.mod` among them, starts with the byte order mark of UTF-16 or UTF-32, THEN the compiler MUST refuse the file with an error that names the file and the encoding, except at the revision `ears diff` compares with (S16.5).

3. The project file

ears.mod sits at the root of a project. It names the version of earslang the project is written in, as go.mod names a Go version, and holds the project's settings. ears init creates it. It is optional; without one, the defaults in S2.7 apply.

# ears.mod
earslang 0.1
spelling shall
layout keep
fix-skip comma full-stop
system the app
system the phone app
Line Means How many
earslang <version> the language version exactly one
spelling must or spelling shall how the standard form writes the keywords any number; a later one replaces an earlier one; must if absent
layout collapse or layout keep how ears fix lays out a rule it rewrites: on one line, or on the lines it was written on any number; a later one replaces an earlier one; collapse if absent
fix-skip <code or name> … rewrites of ears fix the project does not want (§11.2) any number; none if absent
system <name> a system that may be the subject of a verb-form rule any number
# … a comment any number

spelling decides only what ears fix and the markdown, HTML and Gherkin exports write. Both spellings are accepted in every project, and the strength in the JSON is the same either way:

spelling ears fix and the markdown, HTML and Gherkin exports write Strength in the JSON
must (the default) MUST, MUST NOT must; must, negative
shall SHALL, SHALL NOT must; must, negative
rulesOpen in playground
- S2.1: An `ears.mod` file MUST hold exactly one line that names the earslang version.
- S2.2: An `ears.mod` file MAY hold a spelling line, whose value is `must` or `shall`.
- S2.3: An `ears.mod` file MAY hold any number of system lines.
- S2.4: An `ears.mod` file MAY hold comment lines that start with `#`.
- S2.5: WHEN an `ears.mod` file holds any other line, THEN the compiler MUST report an error.
- S2.6: WHEN a project names a version the compiler does not know, THEN the compiler MUST report an error.
- S2.7: WHEN the compiler reads files that no project holds, THEN the compiler MUST apply the newest version it knows, the spelling `must`, the layout `collapse` and no declared systems.
- S2.8: An `ears.mod` file MAY hold a layout line, whose value is `collapse` or `keep`.
- S2.9: WHEN a fix-skip line names something that is neither the code nor the name of a rewrite in Table 11.2, THEN the compiler MUST report an error.
- S2.10: An `ears.mod` file MAY hold any number of fix-skip lines.

4. Fence attributes

Attributes follow the language after a comma, as in Rust's doc tests. A .ears file takes no attributes; it is read as a plain ```ears block.

Fence Parsed Checked In the compiled rules Run by Use
```ears yes yes yes ears check rules
```ears,example yes yes, except [from] and [table] tags no ears test examples in documentation
```ears,compile_fail yes must fail no ears test examples of mistakes
```ears,compile_fail,E0012 yes must raise that code no ears test an example of one mistake
```ears,ignore no no no — drafts and sketches
rulesOpen in playground
- S3.1: WHEN a fence names an attribute other than `ignore`, `example` or `compile_fail`, THEN the compiler MUST report an error.
- S3.2: WHEN a fence names more than one attribute, THEN the compiler MUST report an error.
- S3.3: A `compile_fail` attribute MAY be followed by a comma and one diagnostic code.
- S3.4: WHEN a fence names `ignore`, THEN the compiler MUST NOT parse the block.
- S3.5: WHEN a fence names `example`, THEN the compiler MUST NOT add the block to the compiled rules.
- S3.6: WHEN a fence names `example`, THEN the compiler MUST NOT resolve the `[from]` and `[table]` tags in the block.
- S3.7: WHEN a fence names `compile_fail`, THEN the compiler MUST NOT add the block to the compiled rules.
- S3.8: WHEN `ears test` runs, THEN it MUST report every example block that raises an error, other than an error about a `[from]` or `[table]` tag (S3.6).
- S3.9: WHEN `ears test` runs, THEN it MUST report every `compile_fail` block that names no code and raises no error.
- S3.10: WHEN a `compile_fail` block names a code and raises no diagnostic of that code, THEN `ears test` MUST report it.
- S3.11: WHEN `ears test` compiles an example or `compile_fail` block, THEN it MUST compile the block with the project's `ears.mod`.
- S3.12: `ears test` MUST NOT count a diagnostic in `ears.mod` against a block.

An example means what the same rule means in its project: a rule that leaves out THEN before a system the project declares passes as an example too. What is wrong in ears.mod itself is reported by ears check.


5. Rules and prose

A .ears file or ears block is markdown. The compiler reads it as markdown does, a paragraph or list item at a time: an optional front matter, then rules and prose.

document     = [ front-matter ] { block }
front-matter = "---" newline { meta-line | blank-line } "---" newline
meta-line    = key ":" [ " " ] text { continuation }
key          = lower { lower | digit | "-" | "_" }
block        = rule | prose | blank-line
rule         = [ list-marker ] [ ID ": " ] sentence { [ " " ] tag } { continuation }
list-marker  = ( "-" | "*" | "+" | number "." ) " "
ID           = letter { letter | digit | "-" | "_" | "." }
tag          = "[proposed]" | "[dropped]"
             | "[from " ID { "," [ " " ] ID } "]" | "[table " name "]"
continuation = newline text            (the next line of the same paragraph or list item)

The grammar blocks use the notation of the Go specification: | separates choices, ( ) groups, [ ] is optional, { } repeats zero or more times, and text in double quotes stands for itself. Text in round brackets at the end of a line explains it. The other names: newline is the end of a line; text is any characters up to the end of the line; blank-line is a line that holds nothing or only spaces; lower is a letter from a to z; letter is a letter from a to z or A to Z; digit is a digit from 0 to 9; number is one or more digits; name is any text without square brackets; prose is what the table below reads as prose; sentence is in §6.2. Blank lines in front matter are ignored.

Rule or prose. In earslang, as in RFC 8174, a sentence with a keyword in capitals is normative. A list item is read whole: its lines are joined, and its end is the end of the rule. The lines of a paragraph are joined the same way, as a rendered page joins them, except that a line holding a keyword, after lines that already hold one, starts the next rule. So a rule wrapped over two lines is one rule, and a list of rules one to a line, as other EARS tools write them, is still a list. A full stop at the end of a rule is optional.

Part Starts with an ID Holds a keyword Read as
list item or paragraph line yes yes a rule with an ID
list item or paragraph line yes no error: an ID with no keyword
list item or paragraph line no yes a rule with no ID: in force, but nothing can cite it
list item no no prose; a warning if it holds "must" or "shall" in lowercase
paragraph line no no prose, or part of a rule in the same paragraph, before or after it (S4.16); a warning if it holds a structure word (§6.1) and "must" or "shall" in lowercase
heading, table row or quote yes or no yes or no prose

A keyword is one of the words in Table 7, in capitals, or, in a rule with no structure word, a lowercase "shall" (§6.3). Headings, table rows and quotes are always prose: the compiler reads no meaning into them.

IDs are written by the writer, at the start of the rule, with a colon: R7:, FR-001:, APP-512.1:. An ID holds at least one digit, so a line that starts with "Note:" is never read as an ID. IDs are optional: a rule without one is in force, but nothing can cite it, and ears diff can follow it only by its text. Do not give a used ID to another rule, even after its rule is dropped or deleted; the compiler sees only the IDs in the files.

Front matter at the top of a .ears file or block holds key: value lines for every rule in that file or block: a source, a Jira key, an owner, an extension's field. A key starts with a lowercase letter, followed by lowercase letters, digits, hyphens and underscores. The compiler checks the key's form, not its value. It carries each line into the output as raw text; it is not YAML. The extension that uses a key checks its value.

exampleOpen in playground
---
source: Support tickets 4411, 4502,
  and the March field interviews
jira: APP-512
---

## Retries

These replaced the fixed one-minute retry after the March incident.

- R7: WHEN a change fails to send, THEN the app MUST retry it with a growing delay. [from R3]
- R8: The app SHOULD show the next retry time. [proposed]
- WHILE offline, THEN the app MUST queue every change.

An ID with no keyword fails:

fails the checksOpen in playground
- R9: The app saves every change.
rulesOpen in playground
- S4.1: WHEN a list item or paragraph line starts with an ID or holds a keyword, THEN the compiler MUST read it as a rule.
- S4.2: WHEN a list item or paragraph line starts with an ID and holds no keyword, THEN the compiler MUST report an error.
- S4.3: The compiler MUST read every other list item, paragraph line, heading, table row and quote as prose, except a paragraph line it joins to a rule (S4.16).
- S4.4: The compiler MUST NOT check prose.
- S4.5: WHEN a list item, or a paragraph that holds a structure word, is read as prose and holds `must` or `shall` in lowercase, THEN the compiler SHOULD report a warning that suggests the capital form.
- S4.6: An ID MUST start with a letter, hold at least one digit, and hold only letters, digits, hyphens, underscores and full stops.
- S4.7: An ID MUST NOT end with a full stop.
- S4.8: WHEN two rules in one project share an ID, THEN the compiler MUST report an error that names both places.
- S4.9: WHEN a rule is a list item, THEN the compiler MUST read its indented continuation lines as part of the rule.
- S4.10: WHEN a `.ears` file or a block starts with a line of three hyphens, THEN the compiler MUST read the lines up to the next such line as front matter.
- S4.11: The compiler MUST carry each front matter line into the output as a key and its raw text, in the order written.
- S4.12: The compiler MUST NOT check the value of a front matter line.
- S4.13: The compiler MUST give every rule the front matter of its `.ears` file or its block.
- S4.14: The compiler MUST NOT give a rule the front matter of the `.md` file that holds its block.
- S4.15: WHEN a file holds a rule with an ID and a rule without one, THEN the compiler SHOULD report a warning at the rule without one.
- S4.16: The compiler MUST join each line of a paragraph to the line before it, as it joins a list item's continuation lines.
- S4.17: WHEN a line of a paragraph holds a keyword or starts with an ID, and the lines it would join already hold a keyword, THEN the compiler MUST start a new rule at that line.

Rules that contradict each other. Two rules in force contradict each other when they have the same subject, the same conditions, the same response and the same strength, and one is the negative of the other. The check compares text after normalising spaces and capitals. It finds exact contradictions only; a contradiction in meaning stays with review.

rulesOpen in playground
- S11.2: WHEN two rules in force share a subject, the same conditions, the same response and the same strength, and one is the negative of the other, THEN the compiler MUST report an error that names both.

6. Sentences

6.1 Structure words in capitals

The structure of a sentence is marked in capitals, as RFC 8174 does for its keywords. The same words in lowercase are ordinary text.

Word Role From
WHERE an optional feature EARS
WHILE a state that holds EARS
WHEN an event EARS
IF an unwanted event EARS
THEN the subject starts here; required after the conditions, except before a declared system (§6.2) EARS (after IF), extended to every condition

WHERE, WHILE, WHEN and IF are the condition words. The keywords, which give a rule its strength, are in §7.

A structure word or keyword is a whole word: a run of letters with no letter on either side, so MUSTARD is not MUST. Text inside backticks or double quotes (straight or curly) is ordinary text, so a rule can mention WHEN or "MUST" without either counting. Any Unicode space character (Unicode's space separators, such as a no-break space or a thin space) counts as a space. One such character is also the one space between the two words of a keyword such as MUST NOT; a tab, two spaces or any other blank there is an error (S8.7, and S8.3 for NOT RECOMMENDED).

GIVEN, AND and BUT are not structure words. GIVEN is refused, because Gherkin's Given is often a past action ("Given I added an item"), which is not a state; the message points to WHILE for a state and WHEN for an event. AND and BUT in capitals are read as ordinary text, with a warning.

rulesOpen in playground
- S5.1: The compiler MUST count a structure word or keyword only as a whole word in capitals.
- S5.2: The compiler MUST read text inside backticks or double quotes as ordinary text.
- S5.3: The compiler MUST read any Unicode space character, such as a no-break space, as a space.
- S5.4: WHEN a rule holds the word `GIVEN`, THEN the compiler MUST report an error that suggests `WHILE` for a state and `WHEN` for an event.
- S5.5: WHEN a rule holds the word `AND` or the word `BUT`, THEN the compiler SHOULD report a warning that it is read as ordinary text.

6.2 Form

sentence       = verb-form | adjective-form
verb-form      = [ conditions start ] subject " " verb " " response [ "." ]
adjective-form = [ conditions start ] subject " " ( "is" | "are" ) " " adjective [ " to " response ] [ "." ]
               | [ conditions start ] subject " " ( "is" | "are" ) " OPTIONAL" [ "." ]
conditions     = condition { [ "," ] " " condition }
condition      = ( "WHERE" | "WHILE" | "WHEN" | "IF" ) " " text
start          = [ "," ] " THEN " | " "     (THEN may be left out before a declared system)
verb           = "MUST" | "MUST NOT" | "SHOULD" | "SHOULD NOT" | "MAY" | "SHALL" | "SHALL NOT"
adjective      = "REQUIRED" | "RECOMMENDED" | "NOT RECOMMENDED"

subject and response are text; the table "Where the subject starts" below says where the subject starts.

The EARS patterns, in the standard form and the other forms earslang accepts:

Pattern Standard form Also accepted: without the commas Also accepted: without THEN, before a declared system
Ubiquitous The <system> MUST <response>. — —
Ubiquitous, adjective form X is REQUIRED. / X is REQUIRED to <response>. — —
State WHILE <state>, THEN the <system> MUST <response>. WHILE <state> THEN the <system> MUST … WHILE <state>, the <system> MUST …
Event WHEN <trigger>, THEN the <system> MUST <response>. WHEN <trigger> THEN the <system> MUST … WHEN <trigger>, the <system> MUST …
Optional feature WHERE <feature>, THEN the <system> MUST <response>. WHERE <feature> THEN the <system> MUST … WHERE <feature>, the <system> MUST …
Unwanted IF <trigger>, THEN the <system> MUST <response>. IF <trigger> THEN the <system> MUST … IF <trigger>, the <system> MUST …
Combined WHILE <state>, WHEN <trigger>, THEN the <system> MUST <response>. WHILE <state> WHEN <trigger> THEN the <system> MUST … WHILE <state>, WHEN <trigger>, the <system> MUST …

The standard form keeps the EARS comma before THEN and between conditions. Both commas are optional; ears fix adds them.

How a sentence is split:

  1. Find the keyword (§7). The text after it is the response.
  2. Each condition word before the keyword starts a condition. A condition runs to the next structure word; a comma at its end is dropped. A rule with a condition starts with it: words before the first condition would belong to no part of the rule, so they are an error (S6.18).
  3. The subject is the text between THEN and the keyword. With no condition, it is everything before the keyword. With a condition and no THEN, it is the declared system that the words before the keyword end with.

The usual order of conditions is WHERE, then WHILE, then WHEN or IF.

Where the subject starts:

Conditions THEN Result
none no the subject is everything before the keyword
none yes error: THEN with no condition
some yes the subject is the text after THEN
some, and one after THEN yes error: a condition after THEN (S6.17)
some no, and the words before the keyword end with a declared system the subject is that system; ears fix adds THEN before it
some no, and no declared system ends them error: THEN is required after a condition; the help shows where it goes

THEN can be left out only before a declared system, because only then is the subject known without guessing. A rule written "WHEN x, THE SYSTEM SHALL y", as some EARS tools write it, passes in a project whose ears.mod holds system the system. A comma alone does not mark the subject: a comma inside the condition ("WHEN a file, folder or link is saved the app MUST sync it") looks the same as one before the subject.

The help for a missing THEN shows the sentence with THEN after the last comma before the keyword. ears fix does not apply it, because that comma may belong to the condition. With no comma before the keyword, the help shows the standard form with THEN.

A [table T2] tag points to a heading in the same file whose first word is T2, followed by a space or the end of the heading (for example ### T2 Offline and sync), with a pipe table under it. ### T2: Offline does not match, since its first word is T2:. In 0.1 the compiler checks only that the table is there, not what is in it. Declared states and the truth tables built from them are not in 0.1 (open question Q2).

A table may also hold a list that belongs to one rule, such as the body types a request may have, in place of a long list inside the sentence. The rule names it the same way, and the compiler checks the same thing: that it is there.

exampleOpen in playground
- R1: The client MUST send every body type in table T3. [table T3]

A lowercase "when", "whenever", "while" or "if" after the keyword is usually a condition hidden in the response ("The app MUST export it when the user asks."), so the compiler warns. The fix is to move it to the front as a capital WHEN. If it is not a condition, reword it: "check whether", not "check if".

The compiler checks structure, which capitals, keywords, THEN and tags mark, and not grammar. A full stop inside a rule is ordinary text: "e.g. PNG", "U.S. Dollars" and a second sentence of prose are all part of the response. A second duty belongs in a rule of its own, with its own keyword (S6.3).

rulesOpen in playground
- S6.1: The compiler MUST NOT require a full stop at the end of a rule.
- S6.2: The compiler MUST resolve keywords as §7 says.
- S6.3: WHEN a rule holds two or more keywords, THEN the compiler MUST report an error.
- S6.4: WHEN the response of a verb-form rule is empty, THEN the compiler MUST report an error.
- S6.5: WHEN a rule has a condition, no `THEN`, and no declared system at the end of the words before its keyword, THEN the compiler MUST report an error that shows where `THEN` goes.
- S6.6: WHEN a rule has `THEN` and no condition, THEN the compiler MUST report an error.
- S6.7: WHEN the subject of a rule holds a comma, THEN the compiler SHOULD report a warning.
- S6.8: WHEN the project declares any system and the subject of a verb-form rule is not one of them, THEN the compiler MUST report an error.
- S6.9: The compiler MUST compare subjects with declared systems without regard to capital letters.
- S6.10: WHEN the conditions of a rule are out of the usual order, THEN the compiler SHOULD report a warning.
- S6.11: WHEN a rule has two or more conditions and no `[table]` tag, THEN the compiler SHOULD report a warning.
- S6.13: WHEN a `[table]` tag names no heading in the same file whose first word is that name and that has a table under it, THEN the compiler MUST report an error.
- S6.14: WHEN the response of a rule holds `when`, `whenever`, `while` or `if` in lowercase as a word, THEN the compiler SHOULD report a warning that it may hide a condition.
- S6.15: WHEN a rule has a condition and no `THEN`, and the words before its keyword end with a declared system, THEN the compiler MUST read that system as the subject.
- S6.16: WHEN the subject of a verb-form rule is empty, THEN the compiler MUST report an error.
- S6.17: WHEN a rule has a condition after its first `THEN`, THEN the compiler MUST report an error.
- S6.18: WHEN a rule that has a condition has words before its first condition, THEN the compiler MUST report an error.

6.3 Classic EARS

A rule with no structure word is read as classic EARS, whatever the case of its keyword. Its condition words are found at the start of the sentence or after a comma, and a lowercase "shall" counts as a keyword. So a plain list of classic EARS sentences, as other EARS tools write them, is valid earslang when a comma or "then" follows each sentence's conditions, or its subject is a system declared in ears.mod (S7.4): every paragraph or list item is a rule with no ID.

Structure word in the rule Result
one or more only capitals are structure; lowercase "when", "shall" and the rest are ordinary text
none classic EARS: "when", "while", "where" and "if", in any case except capitals, at the start or after a comma are conditions; the subject starts after "then" when there is one, otherwise at the declared system that the words before the keyword end with, and otherwise after the last comma before the keyword, when that comma follows every condition; "shall" and "shall not" are keywords, as are the capital ones

The last comma is a guess, and it can be silently wrong: in "When a file, folder or link is saved the app shall sync it" it gives the subject "folder or link is saved the app". Declaring the project's systems makes the reading exact, and turns a wrong guess into an error (S6.8).

A classic rule with a condition starts with it, as any rule does: in "Only, when asked, the app shall save." the word "Only" is in no part of the rule, so it is an error (S6.18).

rulesOpen in playground
- S7.1: WHEN a rule holds no structure word, THEN the compiler MUST read it as classic EARS.
- S7.2: WHEN a rule read as classic EARS uses a lowercase condition word or a lowercase `shall`, THEN the compiler MUST record it as classic in the output.
- S7.3: WHEN a classic rule has a condition and no `then`, and the words before its keyword end with a declared system, THEN the compiler MUST read that system as the subject.
- S7.4: WHEN a classic rule has a condition and no `then`, the words before its keyword end with no declared system, and no comma before its keyword follows every condition, THEN the compiler MUST report an error.
exampleOpen in playground
When the user saves, the app shall write the file within one second.
When the user closes the file, the app MUST ask before discarding changes.

7. Keywords

earslang accepts all eleven keywords of BCP 14. The verbs take the EARS form. The adjectives follow "is" or "are", as the RFCs themselves write them.

Table 7: Keywords

Written Form Strength in the output
MUST, SHALL the app MUST … must
MUST NOT, SHALL NOT the app MUST NOT … must, negative
SHOULD the app SHOULD … should
SHOULD NOT the app SHOULD NOT … should, negative
MAY the app MAY … may
REQUIRED X is REQUIRED. / X is REQUIRED to … must
RECOMMENDED X is RECOMMENDED. / X is RECOMMENDED to … should
NOT RECOMMENDED X is NOT RECOMMENDED. / X is NOT RECOMMENDED to … should, negative
OPTIONAL X is OPTIONAL. may
shall, shall not (classic EARS only, §6.3) the app shall … must; must, negative

The two words of a keyword are separated by one space; any Unicode space character, such as a no-break space, counts as one (S5.3).

Not accepted:

Written Why Message
MAY NOT, or MAY followed by "not" BCP 14 does not define it, and English reads it two ways error: use MUST NOT (not allowed), or MAY with a response that says what is allowed ("MAY skip the sync")
an adjective not after "is" or "are" it does not fit either form error: write "X is REQUIRED", or use the verb of the same strength: MUST for REQUIRED, SHOULD for RECOMMENDED, SHOULD NOT for NOT RECOMMENDED, MAY for OPTIONAL; after "not", the help keeps the not: NOT RECOMMENDED or SHOULD NOT for RECOMMENDED, MAY or OPTIONAL for REQUIRED, REQUIRED or MUST for OPTIONAL
OPTIONAL to … it does not fit the adjective form error: use MAY
an adjective followed by words other than "to" and a response, as in "Logs are REQUIRED for audits." it fits neither form, and read without the words the rule would lose them error: use the verb of the same strength with a response ("Logs MUST for audits."), or, for an adjective other than OPTIONAL, write "to" and a response before the words; a condition in the words goes first ("WHEN asked, THEN the log MUST ." for "The log is REQUIRED WHEN asked.")
MUST, SHALL or SHOULD, or a classic "shall", followed by "not" in another case, after spacing other than one space or a character that shows nothing, joined to it by a hyphen, a dash, an underscore or a slash ("MUST-NOT"), or with markdown emphasis between them (MUST **NOT**) it reads as the keyword without the not, which may be the opposite of what is meant error: write MUST NOT (or "shall not") if the rule forbids, without emphasis; otherwise reword so that the keyword is not followed by "not"; when only the spacing is wrong, write the keyword with one space.

Lowercase must, should and may are ordinary English (RFC 8174). A list item or paragraph whose only "must" is lowercase is prose; in a list item, or in a paragraph that holds a structure word, it gets a warning that suggests the capital form (S4.5).

rulesOpen in playground
- S8.1: The compiler MUST accept every keyword Table 7 lists.
- S8.2: The compiler MUST count an adjective as the keyword of its rule.
- S8.3: WHEN an adjective does not follow `is` or `are`, THEN the compiler MUST report an error.
- S8.4: WHEN `MAY` is followed by the word `not` in any case, after the characters S8.7 names, THEN the compiler MUST report an error that offers both readings.
- S8.5: WHEN `OPTIONAL` is followed by `to`, THEN the compiler MUST report an error that suggests `MAY`.
- S8.6: The output MUST record the strength of each rule as Table 7 gives it.
- S8.7: WHEN `MUST`, `SHALL` or `SHOULD`, or `shall` in a rule read as classic EARS, is followed by the word `not`, after blanks, characters that show nothing (such as a zero-width space), hyphens, dashes, underscores, slashes or asterisks, and the two are not a keyword Table 7 lists, THEN the compiler MUST report an error that quotes what was written, with a help that offers both readings or, for a fault of spacing alone, says to write the keyword with one space.
- S8.8: WHEN an adjective is followed by words that are not `to` and a response, THEN the compiler MUST report an error whose help gives the rule with the verb of the same strength and keeps the words.
exampleOpen in playground
- A title is REQUIRED.
- The user is REQUIRED to confirm before deleting.
- WHEN the user saves THEN the app MUST write the file within one second.

Two keywords fail:

fails the checksOpen in playground
- The app MUST save and SHOULD sync.

IF without THEN fails:

fails the checksOpen in playground
- IF the disk is full, the app MUST warn the user.

Any condition without THEN fails:

fails the checksOpen in playground
- WHEN the user saves, the app MUST write the file.

GIVEN fails:

fails the checksOpen in playground
- GIVEN the user is signed in, WHEN they save, THEN the app MUST sync.

A Gherkin step with an ID and no strength fails (without an ID, it would be prose):

fails the checksOpen in playground
- R9: WHEN a request is sent THEN it is queued.

MAY followed by "not" fails:

fails the checksOpen in playground
- The app MAY not sync on a metered network.

Two conditions without a [table] tag pass, with a warning:

exampleOpen in playground
- WHILE offline, WHEN a request is sent, THEN the app MUST queue it.

8. Declarations

Systems are declared in ears.mod (§3) with system lines. When a project declares any, the subject of every verb-form rule must be one of them (S6.8).

rulesOpen in playground
- S9.1: WHEN a project declares the same system twice, THEN the compiler SHOULD report a warning.

9. Status and [from] tags

A rule is in force unless a tag says otherwise. A rule is accepted when the change that adds it is merged. Only the exceptions are written, as one tag after the full stop. A tag counts only at the end of the rule, after any full stop.

Tag Meaning
none in force (accepted)
[proposed] written, not yet agreed, so not in force
[dropped] rejected; kept in the file for the record, not in force. The rule may be deleted instead.

A rule that waits on an answer stays [proposed]. The question is written in the markdown around it, not in the rule, and links to it: [R3](#R3). Who changed a rule, and when, is in git's history.

[from R3] says a rule was derived from another rule, and the compiler checks that R3 exists. The front matter's source: is the convention for evidence outside the project (an issue, a URL, an interview), as free text that nothing checks.

rulesOpen in playground
- S10.1: WHEN a rule has no status tag, THEN the compiler MUST treat it as in force.
- S10.2: A rule MUST hold no more than one status tag.
- S10.3: WHEN a rule holds a tag the grammar does not list, THEN the compiler MUST report an error.
- S10.6: WHEN a `[from]` tag names a rule that does not exist, THEN the compiler MUST report an error.
- S10.7: The output MUST record each rule's status.

A tag [accepted] is refused with the help "rules are in force unless tagged".


10. Combining files

The compiled rules are the same whatever order the files are read in, and no file can override another. A rule is replaced by rewording it in place and keeping its ID; git keeps the old wording. A [replaced-by] tag, which would keep the old rule beside the new one, is not in 0.1.

rulesOpen in playground
- S11.1: The compiler MUST give the same output whatever order it reads the files in.

The check for two rules that contradict each other is in §5.


11. Commands

One program, ears, with subcommands. Where Rust, Go and CUE agree, earslang follows them. This table is the one list of commands; other documents link here.

Command Does
ears check [files or patterns] parses and checks the rules; writes nothing
ears test runs the example and compile_fail blocks
ears fmt layout only; --check exits 1 if anything would change; --diff shows the changes without writing
ears fix the exact rewrites that ears explain describes (§11.2); --check and --diff as for fmt
ears export --out <format> writes the compiled rules as an export; JSON by default
ears import --from <format> brings rules in from another format
ears diff --against <git revision> a report of what changed in the rules since that revision (§11.5)
ears explain <code> the long explanation of a diagnostic, or what a rewrite of fix does (§11.2)
ears init creates ears.mod
ears mcp runs the MCP server for AI tools
ears version prints the version; also ears -V and ears --version
ears help [command] prints this usage, or a command's usage and flags; also ears -h and ears --help
ears <name> runs the plugin ears-<name> from the PATH

A plugin is a program named ears-<name>, as cargo-<name> is for Cargo and git-<name> for git. It adds a subcommand, such as ears states. It reads the compiled rules by running ears export --out json.

rulesOpen in playground
- S20.1: WHEN the first argument is not a command the compiler has and a program named `ears-` followed by that argument is on the PATH, THEN the compiler MUST run that program with the remaining arguments.
- S20.2: WHEN a plugin has the name of a built-in command, THEN the compiler MUST run the built-in command.
- S20.3: WHEN a plugin on the PATH has the name of a built-in command, THEN the compiler SHOULD report a warning.

11.1 ears fmt

rulesOpen in playground
- S12.1: `ears fmt` MUST NOT change a word or a punctuation mark.
- S12.2: `ears fmt` MUST indent the continuation lines of a list item to the item's text.
- S12.3: `ears fmt` MUST write tags at the end of their rule, in the order `[from]`, `[table]`, status.
- S12.4: `ears fmt` MUST NOT rewrap the text of a rule.
- S12.5: `ears fmt` MUST NOT change front matter.
- S12.6: `ears fmt` MUST NOT change anything outside `.ears` files and `ears` blocks.
- S12.7: IF a file has an error, or `ears.mod` has one, THEN `ears fmt` MUST leave the file unchanged and report the error.
- S12.8: WHEN `ears fmt` runs twice, THEN the second run MUST change nothing.
- S12.9: WHEN `ears fmt` is given `--check`, THEN `ears fmt` MUST write nothing.
- S12.10: WHEN `ears fmt` is given `--check` and would change a file, THEN it MUST exit with status 1.
- S12.11: IF a rule's new layout would change a rule, a heading, the front matter, a block, or where one of them starts or ends, THEN `ears fmt` MUST leave that rule as it is.
- S12.12: WHEN `ears fmt` writes a file that starts with a byte order mark, THEN it MUST keep the mark.

11.2 ears fix

fix makes only exact rewrites: the same meaning by definition, with no judgement. Everything else is a suggestion that ears check prints. "MUST" below means the project's spelling (§3): SHALL in a project with spelling shall.

Each rewrite has a code and a name. A project skips one with a fix-skip line in ears.mod that names it by either (fix-skip comma F0006); fix then leaves that part of every rule as it is written, and makes the others. A code is never given to another rewrite.

Table 11.2: Rewrites

Code Name Written ears fix writes
F0001 classic classic "when", "while", "where", "if", "then", "shall", "shall not" WHEN, WHILE, WHERE, IF, THEN, SHALL, SHALL NOT, with THEN added where the classic reading put the subject
F0002 keyword SHALL / SHALL NOT, or MUST / MUST NOT the project's spelling
F0003 adjective "is REQUIRED to <verb>" / "are REQUIRED to <verb>"; RECOMMENDED; NOT RECOMMENDED MUST <verb>; SHOULD <verb>; SHOULD NOT <verb>
F0004 comma a missing comma after a condition the comma
F0005 then a missing THEN before a declared system (S6.15) THEN
F0006 full-stop a missing full stop at the end of the sentence the full stop
F0007 and AND or BUT in capitals that starts a clause in the conditions: after a comma, or at the start of a line the condition word before it: "WHILE a, AND b," becomes "WHILE a, WHILE b,"
— — a rule that fix rewrites, written on more than one line one line; with layout keep in ears.mod, the same lines, each starting at the word it started at, with an added THEN at the start of its line
— — an older language version in ears.mod the changes that version needs (§13)

Skipping classic leaves a classic rule's lowercase words as they are and adds no THEN; keyword still puts its keyword in the project's spelling. Skipping then does not stop classic adding THEN, because a rule in capitals needs it.

Never rewritten: MAY NOT, a lowercase "must", a missing THEN in a rule with structure words whose subject is not a declared system, GIVEN, "X is REQUIRED." with nothing after it, AND or BUT inside a clause ("WHEN the user saves AND closes the file") or in a response, and IDs: fix never adds, removes or changes an ID. AND or BUT in a response may join two duties, but splitting the rule is not exact ("MUST save the file AND the log"), so the warning suggests it and fix leaves it.

Replacing AND or BUT can leave a rule with two conditions and no [table] tag. The rule had two conditions before, written another way, so fix makes the change, and ears check then reports the warning for the missing table (S6.11).

A rewrite fails a check when it would raise an error, raise a warning more often than before (except the warning of S6.11 for two conditions with no table), change what the rule says, or stop the text being read as a rule.

rulesOpen in playground
- S13.1: `ears fix` MUST make only the rewrites Table 11.2 lists.
- S13.2: IF a rewrite would make a rule fail a check, THEN `ears fix` MUST NOT make it.
- S13.3: IF a rewrite would make a rule fail a check, THEN `ears fix` SHOULD print it as a suggestion.
- S13.4: IF a file has an error, or `ears.mod` has one, THEN `ears fix` MUST leave the file unchanged and report the error.
- S13.5: WHEN `ears fix` runs twice, THEN the second run MUST change nothing.
- S13.6: WHEN `ears fix` is given `--diff`, THEN `ears fix` MUST show its changes and write nothing.
- S13.7: WHEN `ears fix` is given `--check`, THEN `ears fix` MUST write nothing.
- S13.8: WHEN `ears fix` is given `--check` and would change a file, THEN it MUST exit with status 1.
- S13.9: WHEN replacing `AND` or `BUT` with a condition word leaves a rule with two conditions and no `[table]` tag, THEN `ears fix` MUST make the change.
- S13.10: WHEN `ears.mod` holds `layout keep`, THEN `ears fix` MUST keep each line break of a rule it rewrites.
- S13.11: WHEN `ears.mod` skips a rewrite with a fix-skip line, THEN `ears fix` MUST NOT make that rewrite.
- S13.12: WHEN `ears fix` writes a file that starts with a byte order mark, THEN it MUST keep the mark.

11.3 ears export and extensions

export is the one way to every output. The built-in exports (JSON, HTML, markdown and Gherkin) and extensions both read the compiled rules. An extension is a program named ears-export-<name> on the PATH. It reads the JSON on standard input and writes its output to standard output. Its own options follow --, as in Cargo: ears export --out <name> -- --draft. The compiler passes them on and reads none of them.

html and md write the rules only: each rule under the headings it sits under, in the order written, with its status tag. A dropped rule stays in place, marked. Prose is not rendered; markdown already renders on GitHub, GitLab and in editors, and a fuller page is an extension's job. The built-in page has one fixed look and takes no stylesheet; another look is an extension. The built-in look is the house style in assets/house.css, built into the compiler and written into each page, with system fonts as the fallback, so a page opens offline.

--out Writes
json (default) the compiled rules, in the versioned JSON form
html the rules as a page, under their headings, in the standard form
md the rules as markdown, under their headings, in the standard form
gherkin scenario skeletons for Cucumber
rulesOpen in playground
- S14.1: WHEN `--out` names a format the compiler does not have and a program named `ears-export-` followed by that name is on the PATH, THEN the compiler MUST run that program.
- S14.2: WHEN the compiler runs an extension, THEN the compiler MUST give it the compiled rules as JSON on standard input.
- S14.3: IF `--out` names a format the compiler does not have and no program has that name, THEN the compiler MUST report an error that lists the built-in exports.
- S14.4: WHEN the compiler renders a rule for people, THEN the compiler MUST write it in the standard form in the project's spelling, whatever its source spelling.
- S14.5: WHEN the compiler writes `html` or `md`, THEN the compiler MUST give every rule that has an ID an anchor equal to its ID, so a link such as `[R3](#R3)` reaches it.
- S14.6: WHEN the compiler renders a rule with a status tag, THEN the compiler MUST show the status beside the rule, where the rule was written.
- S14.11: WHEN the compiler writes `html` or `md`, THEN the compiler MUST NOT show a rule's `[from]` and `[table]` tags.
- S14.7: WHEN the compiler writes `html` or `md`, THEN the compiler MUST write each rule under the headings it sits under and no prose.
- S14.8: WHEN `ears export` runs an extension or `ears import` runs an importer that is not built in, THEN the compiler MUST pass it every argument after `--` unchanged.
- S14.9: IF arguments follow `--` and the export or importer is built in, THEN the compiler MUST report an error.
- S14.10: WHEN the compiler writes `html`, THEN the compiler MUST NOT write anything that makes the page fetch a file from the network.

11.4 ears import

import writes .ears files or markdown with ears blocks from another format. The built-in importers are gherkin and md (a markdown list of requirements). An importer that is not built in is a program named ears-import-<name> on the PATH, which --from <name> runs. Three ship with ears: ears-import-kiro, ears-import-speckit and ears-import-openspec, for the specs of Kiro, Spec Kit and OpenSpec.

The md importer and the importers for Kiro, Spec Kit and OpenSpec are experimental: a work in progress, not yet fully checked, whose output may change in a later release. Each says so on standard error when it runs. Check what they write before relying on it.

Items that state no strength go into ```ears,ignore drafts, from every importer: the writer adds a keyword to each rule and removes ignore. Items that state one go into ```ears blocks. The Gherkin importer writes Given steps as WHILE, for review.

A rule's status comes from its source. A format that can mark a requirement as not yet agreed gives such a requirement the tag [proposed]: in Spec Kit, a [NEEDS CLARIFICATION: …] marker anywhere in the requirement's list item; in OpenSpec, a requirement under ADDED or MODIFIED in a change, which is a proposal until it is archived. The "Status: Draft" line at the top of a Spec Kit spec is not read: Spec Kit writes it on every new spec, so it says nothing about one requirement. A format with no status, such as Gherkin, a markdown list or Kiro's requirements, gives rules in force, since that is what such a file states. A status tag the source already holds, as in an ```ears block of a markdown file, is kept, and no other is added.

The Gherkin importer reads a file with Cucumber's own parser, so it reads a file as Cucumber reads it and refuses a file Cucumber refuses. A byte order mark at the start of the file is taken off first, so such a file is read. Of the languages Cucumber reads, the importer reads only en, the default, and refuses any other, English dialects such as en-au included.

An importer copies a rule's words as its source writes them; it adds no THEN and no full stop. A rule such as Kiro's "WHEN x, THE SYSTEM SHALL y" then passes once ears.mod declares its subject with system the system, and the import notes name the subjects to declare. Once a project declares a system, the subject of every rule with a verb must be a declared one (S6.8). The Gherkin importer builds each sentence from steps, so it writes the standard form.

rulesOpen in playground
- S15.1: WHEN its source marks a rule as not yet agreed and gives the rule no status tag, THEN the importer MUST give the rule the tag `[proposed]`.
- S15.2: The importer MUST list everything it could not map.
- S15.3: WHEN its source states no strength, THEN the importer MUST write the blocks with the attribute `ignore`.
- S15.4: WHEN its source has its own IDs, THEN the importer MUST keep each one as the rule's ID.
- S15.5: The importer MUST NOT choose a strength for a rule whose source gives none.
- S15.6: The importer MUST NOT change the words of a rule it copies from its source.
- S15.7: WHEN its source gives a rule no status tag and does not mark it as not yet agreed, THEN the importer MUST write the rule with no status tag.
- S15.8: WHEN its source gives a rule a status tag, THEN the importer MUST keep that tag.
- S15.9: WHEN a Gherkin source declares a language other than `en`, THEN the Gherkin importer MUST refuse it.
- S15.10: IF markdown would read a rule's line as other than one list item holding the rule's text, THEN the importer MUST NOT write the rule.
- S15.11: IF the importer does not write a rule by S15.10, THEN it MUST list the rule in the import notes.

11.5 ears diff

diff compares the rules with the rules at another git revision and reports what changed in meaning. It is a report and never blocks anything.

Rules with IDs are matched by ID. Rules without IDs are matched by their text; a changed one appears as removed and added, even when only the spelling changed (SHALL to MUST). Give a rule an ID to follow it through changes.

Strength has two ladders. On the positive one MUST is above SHOULD, which is above MAY; on the negative one MUST NOT is above SHOULD NOT. A move down a ladder is a weakening and a move up is a strengthening. A move from one ladder to the other is a reversal. A change can be listed under more than one kind: a rewording that also weakens is both.

Table 11.5: Kinds of change

Listed as Before After
added — R12: The app MUST log errors.
removed R7: The app MUST encrypt backups. (gone)
dropped R7: The app MUST encrypt backups. R7: The app MUST encrypt backups. [dropped]
downgraded R7: The app MUST encrypt backups. R7: The app MUST encrypt backups. [proposed]
accepted R7: The app MUST encrypt backups. [proposed] R7: The app MUST encrypt backups.
reworded R7: The app MUST encrypt backups. R7: The app MUST encrypt every backup.
weakened R7: The app MUST encrypt backups. R7: The app SHOULD encrypt backups.
strengthened R7: The app SHOULD encrypt backups. R7: The app MUST encrypt backups.
reversed R7: The app MUST keep logs. R7: The app MUST NOT keep logs.
rulesOpen in playground
- S16.1: `ears diff` MUST report each changed rule under every kind Table 11.5 gives it.
- S16.2: `ears diff` MUST match rules that have IDs by their IDs.
- S16.3: `ears diff` MUST match rules that have no ID by their text after normalising spaces.
- S16.4: `ears diff` MUST NOT exit with status 1 because of what it reports.
- S16.5: IF a file at the revision `ears diff` compares with starts with the byte order mark of UTF-16 or UTF-32, THEN `ears diff` MUST read it as a file with no rules and report a warning that names the file and the encoding.

12. Output and diagnostics

The compiler's output is JSON. The built-in exports and extensions read only that output. Its JSON Schema is part of this spec, versioned from 0.1, so that extensions can be built against it: spec.schema.json for the compiled rules, diagnostics.schema.json for diagnostics, diff.schema.json for what ears diff --json writes, and a worked example, a small project with the output it compiles to. Format 0.1 is the output of ears 0.1, and S17.13 holds for it: a change to the output changes its version, and the tools that read it are told.

The output lists every file the compiler read, including files with no ears block, with each file's outline: its front matter (raw, unparsed), every heading's level, text, and first and last line, and under each heading its block-level parts (paragraph, list, table, fenced code with its info string, ears block), each with its kind and lines. Each rule records the heading it sits under. Each file's whole text is in the output too, so an extension that needs the prose around a rule (the arguments in a report, a decisions table) takes it by those lines from the output alone: it opens no file, runs on a saved export, and never needs a markdown reader of its own; it only splits a table's cells.

Diagnostics follow Rust: a code and a message, the place, the line with marks under it, and a help line.

error[E0012]: two keywords in one rule
  --> docs/sync.md:14:25
   |
14 | - The app MUST save and SHOULD sync.
   |           ----          ^^^^^^ second keyword
   = help: split into two rules, one keyword each
rulesOpen in playground
- S17.1: The compiler MUST write its output as JSON that names the version of the output format.
- S17.2: The output MUST record for each rule its ID (null for a rule without one), its strength, whether it is negative, its status, its tags, its front matter and whether it was written as classic EARS.
- S17.3: The output MUST record for each rule its file, its first and last line, and the first line of its block (null for a rule outside a block).
- S17.4: Every diagnostic MUST carry a code that is never reused.
- S17.5: Every diagnostic about a file MUST name its file, line and column.
- S17.6: WHEN the compiler reports E0008, E0014, E0015, E0016, E0020, E0029, E0031, E0034 or E0036, THEN its help MUST show the expected form.
- S17.7: WHEN `ears check` is given `--json`, THEN it MUST write its diagnostics as JSON to standard output.
- S17.8: WHEN the compiler finds no error, and no rule gives another status (S12.10, S13.8), THEN it MUST exit with status 0.
- S17.15: WHEN the compiler finds an error and is not used wrongly (S17.16), THEN it MUST exit with status 1.
- S17.16: IF the compiler is used wrongly, THEN it MUST exit with status 2.
- S17.17: The output MUST list inside each list and block quote the block-level parts it holds, with an `ears` block among them carrying its outline.
- S17.9: WHEN the compiler is given `--deny warnings`, THEN the compiler MUST treat every warning as an error.
- S17.10: The output MUST list every file the compiler read, with its front matter as raw text and the level, text, first line and last line of each heading in it.
- S17.11: The output MUST list under each heading its block-level parts, each with its kind and its first and last line.
- S17.12: The output MUST record for each rule the heading it sits under.
- S17.13: WHEN the output format changes, THEN its version MUST change.
- S17.14: The output MUST hold the whole text of every file it lists.

The compiler is used wrongly when it is given a command line it cannot run: an unknown flag or value, or a missing argument. An unknown --out (S14.3), options after -- with a built-in export or importer (S14.9), and an unknown --from are such cases.


13. Compatibility

rulesOpen in playground
- S18.2: WHEN a later version changes the language, THEN `ears fix` MUST move a project to it.

14. Conformance

The examples in this spec are its tests, as in the CommonMark spec. An implementation conforms when ears test passes on this file: every ```ears,example block passes and every ```ears,compile_fail block fails.

Finding fences is CommonMark's job, with its edge cases: fence length, ~~~ fences, fences inside lists and block quotes, and indented code. The fenced code examples of the CommonMark spec, and the table examples of goldmark's table extension (extension/_test/table.txt in goldmark), are part of the suite. goldmark's example 14 is left out: goldmark reads it wrongly once the text ends with a new line, as a file does.

Each rule in this spec should have at least one example that passes and one that fails.

rulesOpen in playground
- S19.2: An implementation MUST find fenced code blocks as the examples of the CommonMark spec require, and tables as goldmark's table examples other than example 14 require.

15. Not in 0.1

ears 0.1 does not have: