# 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]](https://datatracker.ietf.org/doc/html/rfc2119). 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]](https://newadventuresinit.github.io/specpack/minimark/2026-03-31/MiniMark-2026-03-31.md) document. ## Versioning A *Specify spec* is versioned using the [[The riVer Specification v1_draft_20260331T082800Z]](https://newadventuresinit.github.io/specpack/river/v1_draft_20260331T082800Z/riVer-v1_draft_20260331T082800Z.md) 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` ``` markdown 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* ``` markdown 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* ``` markdown /.../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*. ``` markdown # 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. ``` markdown [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*. ``` markdown 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. ``` markdown 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. ``` markdown 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. ``` markdown 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`**. ``` markdown **`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. ``` markdown **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"). ``` markdown **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. ``` markdown [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. ``` markdown **`valid colors`**: * red, * green, * blue. ``` ### Tables **NOTE**: This syntax is inspired by the [[GitHub Flavored Markdown Spec Version 0.29-gfm (2019-04-06)]](https://github.github.com/gfm/). 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]](https://en.wikipedia.org/wiki/Tree_(command))). **NOTE**: The tree terminology used here can be found in [[Wikipedia]](https://en.wikipedia.org/wiki/Tree_(abstract_data_type)). 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]](https://en.wikipedia.org/wiki/Total_order)): 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]](https://en.wikipedia.org/wiki/Total_order#Orders_on_the_Cartesian_product_of_totally_ordered_sets)): `(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]](https://en.wikipedia.org/wiki/Natural_number)). 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]](https://en.wikipedia.org/wiki/Integer)). 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. ``` markdown This is true when * a, * b, * c. ``` #### `a AND b AND c` This is true when 1. a, 2. b, 3. c. ``` markdown 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. ``` markdown 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. ``` markdown 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. ``` markdown * 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. ``` markdown 1. either * a, * b, 2. either * c, * d. ``` ### Logical Quantifiers Quantifiers are expressed in their natural language equivalents (see also [[Wikipedia]](https://en.wikipedia.org/wiki/Quantifier_(logic))). **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]](https://en.wikipedia.org/wiki/Uniqueness_quantification)). ### 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]](https://en.wikipedia.org/wiki/If_and_only_if)). ### Control Flow See also [[Wikipedia]](https://en.wikipedia.org/wiki/Control_flow). #### 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.