← Specify  ·  v1 · draft · 2026-05-22 16:40Z  ·  raw

The Specify Standard v1_draft_20260522T164000Z

Introduction

The Specify standard is a collection of rules, conventions, and best practices for technical specifications which are primarily designed to be consumed and observed by AI agents.

From a classic software engineering perspective, the Specify standard can be understood as American English coding standards.

Conformance

A specification is said to follow or adhere to the Specify standard if it conforms to its rules, conventions, and best practices as far as possible. Such a specification is also called a Specify spec for short.

A Specify spec must explicitly state which Specify version it follows.

The Specify standard is a Specify spec that follows this version of the Specify standard.

Conformance Keywords

These defined terms are based on [RFC 2119].

The following terms carry specific meaning throughout a Specify spec.

must: The requirement is absolute. Not meeting this requirement is a violation of the Specify spec.

must not: The prohibition is absolute. Not observing this prohibition is a violation of the Specify spec.

should: the requirement is strongly recommended. Any deviation from this requirement must be intentional, for a specific reason, and the consequences well understood.

should not: the prohibition is strongly recommended. Any deviation from this prohibition must be intentional, for a specific reason, and the consequences well understood.

may: the requirement is explicitly permitted but not mandatory.

Format

A Specify spec is a [MiniMark 2026-03-31] document.

Versioning

A Specify spec is versioned using the [The riVer Specification v1_draft_20260331T082800Z] versioning scheme.

Naming

Titles

A Specify spec must have a full title that is to be used throughout the Specify spec’s content (see in particular section “Title Heading”).

A Specify spec may have a short title that is to be used for metadata external to the Specify spec’s content, e.g. filenames, URI paths etc.

A Specify spec may use the following well-established title pattern:

  1. The short title is either Camel case or Pascal case.
  2. The full title is either
    • The [SHORT_TITLE] Specification
    • The [SHORT_TITLE] Standard
Example

The Example Specification

Filenames

A Specify spec should use the following filenames:

[SHORT_TITLE]-[REVISION_IDENTIFIER].md for a publication

[SHORT_TITLE].md for the golden source

Example-v1_final_20010101T000000Z.md

Example.md

URIs

A Specify spec may apply the following URI path pattern:

/.../[SHORT_TITLE]/[REVISION_IDENTIFIER] for a publication

/.../Example/v1_final_20010101T000000Z

The [SHORT_TITLE] path component may be lowercased to follow host URL conventions.

Structure

Since a Specify spec is a MiniMark document, the overall document structure is defined by the six levels of ATX headings in the document.

Title Heading

A Specify spec’s title heading is a level 1 ATX heading with inline content consisting of the Specify spec’s full title, followed by exactly one space character, followed by the Specify spec’s riVer revision identifier.

# The Example Specification v1_final_20010101T000000Z

A Specify spec must have a title heading, it must be the first occurrence of an ATX heading in the document, and it must be the only level 1 ATX heading in the document.

A Specify spec may contain content ahead of its title heading as long as the above rules are not violated.

Heading Style

A Specify spec should not have numbered headings that indicate the heading’s position in the heading hierarchy since it is cumbersome and error-prone to readjust numbering after changing the document structure during editing.

A Specify spec should style heading inline content in Title Case.

Sections

A section is a part of a Specify spec starting at a given ATX heading (inclusive) and ending at the next ATX heading of equal or lower level (exclusive). The section heading is the ATX heading at the beginning of the section. The level of a section is the level of its heading.

A subsection of a given section is a section which is contained in this given section.

A section body is a section minus all its subsections.

Content

A semantic chunk is a syntactical block and/or inline structure of markdown combined with additional formatting and usage rules to assign a specific meaning or function to it.

The Specify standard defines the following semantic chunks. A Specify spec must make use of these semantic chunks whenever it wants to express a matching semantic concept.

The specific syntax for a semantic chunk must be used exclusively for indicating this particular semantic chunk throughout a Specify spec.

References

URLs

A URL is marked as a link where the link text equals the link destination which is the URL.

[https://example.com](https://example.com)

External Content

A reference to external content must be placed inside square brackets. The reference should contain the full name of the source and any information required to make the reference unambiguous (e.g. version, variant, edition etc.). The reference should be a link. In this case the link destination must be a URL.

A reference to another published Specify spec must consist of the entire inline content of this publication’s title heading. A Specify spec must not reference the golden source of another Specify spec.

Please refer to [The Example Specification v1_final_20010101T000000Z].

See also [[Wikipedia]](https://en.wikipedia.org/wiki/Reference).

A Specify spec which contains a reference to external content is said to reference this content and is called the referencing specification.

Sections

A section reference within the same or a referenced Specify spec is the literal section, followed by a space character, followed by the section heading inline content enclosed in quotation marks.

Please see section "Example" for an example.

Term Definition

In order to introduce and define a new term (called a defined term), the term is marked as a code span with strong emphasis.

A defined term must have at least one character and must not start or end with the space character.

This is a **`defined term`**.

The definition of a term should occur prior to the first usage of this term in the document.

A Specify spec should use a term definition only to

  • define a new term,
  • redefine an existing term to narrow it down or to avoid ambiguity,
  • stress the particular importance of this term to the specification.

When a defined term is used, the term may be marked with emphasis for clarity.

If a Specify spec uses a defined term from a referenced Specify spec then this usage may also be marked with emphasis.

If a Specify spec uses other well-known, established, or standardized terms, then this usage may also be marked with emphasis.

Name-Value Pairs

A name-value pair associates a particular value with a particular name. It is a paragraph consisting exactly of the name, followed by a colon character, followed by a space character, followed by the value. The name must have at least one character and must not end with a space character. The value must have at least one character and must not start with a space character.

name: value

In addition to the conventional name-value pair there exist a number of more specific variants of name-value pairs that have their own names as follows:

Headword Descriptions

A name-value pair can be used as a term definition in the style of a dictionary or glossary entry. The headword is a defined term and the name-value pair is called a headword description.

**`term`**: definition of *term*

Callouts

A callout is a name-value pair which marks this paragraph with a predefined intention. The following callout keywords are recognized:

NOTE: An explanatory note, a clarification, or additional background information.

TIP: A recommendation, a guideline, a best practice.

WARNING: A caution, an alert, a heads-up.

**NOTE**: An explanatory note

Run-In Heading

A run-in heading is a name-value pair where the name acts as a paragraph-level title and the value acts as the body of text that follows it. The heading (name) is marked with strong emphasis. Technically, it is not a heading and is not part of the document structure (see section “Structure”).

**Background**: This section provides context for the reader.

Technical Information

Filenames, pathnames, variable or constant names, and other code-related values are marked as code spans.

Instructions and data like shell commands, source code, or markup are marked as code blocks.

Placeholders

A placeholder name is a character sequence that

  1. contains only
    • ASCII uppercase alphanumerical characters,
    • underscore characters,
  2. and contains at least one uppercase letter.

A placeholder name may refer to a defined term (where spaces and hyphens are replaced with underscores).

A placeholder is a sequence of characters that consists of a placeholder name enclosed in square brackets.

A placeholder suggests that it must be replaced with an actual value.

[SHORT_TITLE]

Labels

A fenced code block and a list can be labelled with a defined term for reference. The label is a paragraph consisting of the defined term followed by a colon character. The label and the labelled block must be consecutive blocks with no blank line between them.

**`valid colors`**:
* red,
* green,
* blue.

Tables

NOTE: This syntax is inspired by the [GitHub Flavored Markdown Spec Version 0.29-gfm (2019-04-06)].

The vertical bar (also called “pipe”) character is U+007C.

A cell is a non-empty character sequence that

  1. does not contain line endings or pipe characters, and
  2. sits between two pipe characters.

The cell width is the length of the cell’s character sequence (which does not include the pipe characters at the beginning and end).

A row is a line that

  1. starts and ends with a pipe character, and
  2. contains a non-empty sequence of cells, and
  3. contains only single pipe characters (i.e. every pipe character is neither preceded by nor followed by another pipe character).

The row signature is the sequence of cell widths of the sequence of cells it contains.

A table is a fenced code block with language identifier table that consists exactly of a non-empty sequence of rows, such that all rows have an identical row signature.

A row where all cells contain only hyphen characters is called a delimiter row. A table must contain at most one delimiter row and if it does the delimiter row must be the second row of the table.

``` table
| cell | cell | cell |
|------|------|------|
| cell | cell | cell |
| cell | cell | cell |
```

WARNING: This is a visual representation of a table, it is not markdown which is parsed. Hence escaping characters and similar formatting is not necessary.

TIP: Tables should not contain prose to avoid wide cells, which lead to hard-to-read tables.

TIP: Tables with only two columns should be avoided in favor of name-value pairs.

Trees

NOTE: This syntax is inspired by the output of the Unix tree command (see also [Wikipedia]).

NOTE: The tree terminology used here can be found in [Wikipedia].

The following Unicode box-drawing characters are used to draw tree structures:

The box drawings light vertical character is U+2502 (│).

The box drawings light horizontal character is U+2500 (─).

The box drawings light vertical and right character is U+251C (├).

The box drawings light up and right character is U+2514 (└).

An indent segment is a character sequence of exactly four characters that is either

  • │ (U+2502, U+0020, U+0020, U+0020), called a continuation segment, or
  • ` ` (U+0020, U+0020, U+0020, U+0020), called a spacing segment.

A connector is a character sequence that is either

  • ├── (U+251C, U+2500, U+2500, U+0020), called a branch connector, or
  • └── (U+2514, U+2500, U+2500, U+0020), called a terminal connector.

A node label is a non-empty character sequence that does not contain line endings, box drawings light vertical characters, box drawings light horizontal characters, box drawings light vertical and right characters, or box drawings light up and right characters.

A root line is a line consisting solely of a node label. The depth of a root line is defined to be zero.

A node line is a line consisting of a sequence of zero or more indent segments, followed by a connector, followed by a node label. The depth of a node line is the number of its indent segments plus one.

Given a tree structure with size > 1 to depict, a tree is a fenced code block with language identifier tree that consists exactly of one root line followed by a non-empty sequence of node lines, such that

  1. the sequence of lines represents a depth-first traversal of the tree structure, and
  2. the root line depicts the root of the tree structure, and
  3. the depth of every node line equals the depth of the node in the tree structure, and
  4. for a node line of depth d > 1 its indent segment at position p (for p between one and d-1) must be a continuation segment if the node line for the node’s ancestor at depth p uses a branch connector, and a spacing segment if it uses a terminal connector, and
  5. the node lines for the children of a given node must use a branch connector except for the node line of the last child which must use a terminal connector.
``` tree
root/
├── branch1/
│   ├── leaf1.1
│   └── leaf1.2
└── branch2/
    └── leaf2.1
```

Syntax, Punctuation, Grammar

Quotation Marks

A Specify spec must use straight quotation marks (", U+0022) and must not use typographic quotation marks.

Following the established American English rules, quotation marks are used for

  • direct quotes,
  • titles (as long as it is not a defined term),
  • scare quotes (which should be avoided in general in technical writing),
  • nicknames (as long as it is not a defined term),
  • words or letters (as long as it is not a defined term),
  • translations (as an alternative to parentheses).

Procedure Descriptions

A procedure is a step-by-step method to accomplish a specific task or goal. It focuses on the “how” — the precise sequence of actions required to consistently achieve a result. It operates on the logical-conceptual level and is not meant to resemble source code (so-called pseudocode).

A procedure description consists of a chronological sequence of steps with instructions written in plain English. It should be contained in its own section with the section heading containing the word “procedure”.

The following rules and conventions apply exclusively to procedure descriptions contained in a Specify spec. They do not apply to a Specify spec’s content in general.

Foundations

Orderings

A total order on the elements of a set is a binary relation ≤ such that for any elements a, b, c from this set the following is true (see also [Wikipedia]):

  1. a ≤ a (reflexive)
  2. If a ≤ b and b ≤ c then a ≤ c (transitive)
  3. If a ≤ b and b ≤ a then a = b (antisymmetric)
  4. a ≤ b or b ≤ a (strongly connected)

Such a set is called a totally ordered set.

Given two totally ordered sets with elements a, c from the first set and b, d from the second set then the following (called the lexicographic order) is a total order on the Cartesian product of the two sets (see also [Wikipedia]):

(a,b) ≤ (c,d) if and only if

  • a < c, or
    1. a = c, and
    2. b ≤ d.

Ranges

Given a totally ordered set then any description of a range of values from this set must explicitly state if the lowest and highest elements of this range are inclusive or exclusive.

Numbers

The natural numbers are the set {0, 1, 2, 3, ...} (see also [Wikipedia]).

The non-zero natural numbers are the set {1, 2, 3, ...}.

The integers are the set {..., -3, -2, -1, 0, 1, 2, 3, ...} (see also [Wikipedia]).

Both the natural numbers and integers are naturally totally ordered sets.

Enumerations

The definition of an enumeration of values is marked as an ordered list of these values such that the ordinal number of an enumeration value is given by its position in the ordered list. Each enumeration value must be marked as a code span throughout the Specify spec.

Since ordered lists in MiniMark documents always start at 1 and do not allow to skip numbers, these rules also apply to enumeration ordinal numbers.

Every enumeration is a totally ordered set where the enumeration values are compared according to their respective ordinal numbers.

Logical Operators

In order to unambiguously use logical operators in natural language, the following conventions are established.

Logical OR between statements is expressed as an unordered list of comma-separated list items. The comma may be followed by the word “or”.

Logical AND between statements is expressed as an ordered list of comma-separated list items. The comma may be followed by the word “and”.

A nested list indicates a logical precedence grouping (brackets). The list item containing the nested list consists of the word “either” for an unordered nested list, and “both” for an ordered nested list.

Since MiniMark only allows one level of nesting for lists, more complex logic expressions need to be split up first.

a OR b OR c

This is true when

  • a,
  • b,
  • c.
This is true when
* a,
* b,
* c.

a AND b AND c

This is true when

  1. a,
  2. b,
  3. c.
This is true when
1. a,
2. b,
3. c.

a OR (b AND c) OR d

This is true when

  • a,
  • both 1) b, 2) c,
  • d.
This is true when
* a,
* both
  1) b,
  2) c,
* d.

a AND (b OR c) AND d

This is true when

  1. a,
  2. either
    • b,
    • c,
  3. d.
This is true when
1. a,
2. either
   * b,
   * c,
3. d.

(a AND b) OR (c AND d)

  • both 1) a, 2) b,
  • both 1) c, 2) d.
* both
  1) a,
  2) b,
* both
  1) c,
  2) d.

(a OR b) AND (c OR d)

  1. either
    • a,
    • b,
  2. either
    • c,
    • d.
1. either
   * a,
   * b,
2. either
   * c,
   * d.

Logical Quantifiers

Quantifiers are expressed in their natural language equivalents (see also [Wikipedia]).

for all: The stated condition is satisfied by every element from the stated collection of elements.

exists one (exists a): The stated condition is satisfied by at least one element from the stated collection of elements i.e. there could be two or more different elements satisfying the stated condition.

exists exactly one: The stated condition is satisfied by exactly one element from the stated collection of elements (see also [Wikipedia]).

Iff

The phrase if and only if indicates the logical equivalence of the two statements it connects. Either both are true or both are false (see also [Wikipedia]).

Control Flow

See also [Wikipedia].

Steps

A procedure step (or step for short) is the atomic unit of a procedure description. A step should be formulated as an instruction with strong, imperative, action verbs and should focus on one specific goal only.

A step should have a step title for reference and as a brief description of the step.

Sequence

Every procedure description is a non-empty sequence of steps.

A sequence of steps is expressed either as an ordered list or as a sequence of sections all on the same level.

In case of an ordered list the list item should be a run-in heading with the step title as the heading.

In case of a section the section heading should contain the step’s ordinal number in the sequence and the step title.

Conditional Branching

A conditional branch should be expressed in one sentence using one of the following sentence structures.

  • “If [CONDITION], then [ACTION].”
  • “If [CONDITION], then [ACTION], else [ACTION].”
  • “If [CONDITION], [ACTION].”
  • “If [CONDITION], [ACTION]; otherwise, [ACTION].”

The descriptions of conditions and actions should be kept brief to avoid overlong sentences. Defined terms, labels, and section references may be used to split up and reference larger conditions or actions.

Loops

The description of a loop must start with a definition of what the loop is iterating over. In most cases this will be the elements of a list or set (“for each”). The boundary of the steps inside the loop can be expressed in different ways.

If a loop is part of a sequence of steps expressed as an ordered list then the loop iteration definition is a step and all steps inside the loop are an ordered sublist of this list element.

If a loop is part of a sequence of steps expressed as sequence of sections then the loop is fully described in one step (one section). This section may contain subsections to express the steps inside the loop.

Sub-Procedures

Procedure descriptions can be referenced using a label (in case of an ordered list) or a section reference. A step can include the instruction to “continue with” or “proceed to” a referenced procedure.