Record Language

One grammar with no exceptions list means a reader who learned cites on a journey reads cites on a requirement without a second look. Each class answers one question about the field: whether it identifies, links, classifies, narrates, conditions, or reasons. Only names an outside standard fixes stand outside this grammar. Settled by decision/0006-one-field-naming-grammar on the evidence in research/field-naming-evidence and research/cross-layer-trace-evidence.

The Claimwick journey submit-an-expense cites its goal in cites and states each step in statement.

Reviewed forWhich fields break their word class? Look at the field names the change adds, beside the word-class table.

Marked guidance: a reviewer answers this question.

A boolean without a prefix reads as a fact about the record: applies says the constraint applies, and recorded says the entry is recorded. An is or has prefix adds a word that says nothing the value does not already say. The predicate form keeps every boolean readable in a sentence about its record.

Claimwick marks an applying constraint with applies: true instead of isApplicable: true.

Reviewed forWhich boolean fields read as something other than a predicate, or carry an is or has prefix? Look at the boolean fields the change adds.

Marked guidance: a reviewer answers this question.

A recorded date says when something happened or until when it holds: readOn says when an outside source was read, and expiresOn says when an exception ends. effectiveFrom opens a validity span. The shape tells a reader which dates record the world and which open a span.

A Claimwick constraint carries readOn with the date its authority was read, and an exception carries expiresOn with the date it ends.

Checked bylitespec-maintain validate emits no FIELD_NAME_SHAPE diagnostic for a date field.

Marked checkable: the tool named here checks it.

Each kind of text has one reader and one job: a requirement promises, an event reports, and a runbook step instructs. One form per kind means the tense and voice tell the reader what the text does before a word is weighed. Record values stay in the third person, Intent chapter prose says we for the business, and nothing says you.

A Claimwick requirement states "An expense above the threshold waits for its approver."

Reviewed forWhich texts miss the form of their kind? Look at the statements, steps, and meanings the change adds, beside the text-kind table.

Marked guidance: a reviewer answers this question.

Values are read far more than they are written, in records, in the book, and in tool output. One written form per value means a period or a capital letter is never a styling choice but part of the value. The value-style table ends each row with the mechanical test the value meets. Settled by decision/0011-one-grammar-for-names-and-values on the evidence in research/naming-grammar-evidence.

A Claimwick journey step states "The traveller pays for the booking."

Reviewed forWhich statement, meaning, rationale, condition, failure, or title values miss the value style of their row? Look at the values the change adds, beside the value-style table.

Marked guidance: a reviewer answers this question.

Free-text quantities hide behind local habits: one record writes 7 years, another writes seven years, and a check matches neither. ISO dates, ISO durations, and ISO currency codes give every quantity one written form across records and tools. Prose keeps numbers readable by writing each with its unit.

Claimwick holds a room for PT10M and writes "95 percent of checkouts complete" in prose.

Reviewed forWhich quantities use free text or miss their unit? Look at the dates, durations, money values, and numbers the change adds.

Marked guidance: a reviewer answers this question.

A name in the word class of what the record is tells a reader the type before the identifier is opened: a verb opens a use case, a noun phrase opens a goal, and a past participle opens an event. One name form per type keeps listings scannable and citations writable by hand. The record-name table holds the Intent forms beside the Behavior and governance forms.

Claimwick names the journey submit-an-expense, the use case submit-expense, and the setting receipt-threshold.

Reviewed forWhich record names miss the name form of their type? Look at the identifiers the change adds, beside the record-name table.

Marked guidance: a reviewer answers this question.

One spelling per word keeps each term defined once and checked once: license in one record and licence in another split every search and every listing. American spelling is the project spelling for field names and enum values; prose spelling follows the Writing Standard. Each British form reads as a rejected word beside its American spelling.

Claimwick writes license and pseudonymize in field names, values, and prose.

Reviewed forWhich words use British spelling? Look at the field names, enum values, and prose the change adds.

Marked guidance: a reviewer answers this question.

A name an outside standard fixes belongs to that standard: renaming given to fit the word classes breaks every Gherkin reader. The grammar stays complete by exempting exactly these names instead of growing an exceptions list. Gherkin and CloudEvents names are the only exemptions.

A Claimwick scenario keeps given, when, and then, which the word-class table gives no class.

Reviewed forWhich fixed names were renamed to fit the grammar? Look at the Gherkin fields and CloudEvents attributes the change touches.

Marked guidance: a reviewer answers this question.

A code in subject-problem form tells a reader what the finding is about and what is wrong with it before the message is opened. Fourteen problem words, each with one meaning, keep codes comparable across tools: one word for absent, one for expired, and no synonyms. The problem-word table holds each word with its meaning and an example.

A use case with no scenario takes the code use-case-scenario-missing.

Reviewed forWhich finding codes miss the subject-problem form or use a problem word outside the fourteen? Look at the finding codes the change adds, beside the problem-word table.

Marked guidance: a reviewer answers this question.

A message that states a fact survives every reader: the terminal and the book both show what is true. Advice belongs in the finding table on the model page, where it is written once beside the code instead of repeated in every occurrence. Analyzer diagnostics keep their LS numbers and follow the same message rule.

A journey step with no serving use case reports Journey step 'book-a-room#s3' is served by no use case.

Reviewed forWhich finding messages instruct instead of stating a fact, or open without the subject and identifier? Look at the messages the change adds.

Marked guidance: a reviewer answers this question.

A verb names what the command does, so check reads as an action before its arguments are weighed. A flag that names its mode or value reads the same way at every call site, and kebab-case keeps multiword flags writable without quotes. Stable exit codes let scripts tell a clean run from a blocking finding from bad arguments.

The release check runs as litespec model check --release and exits 1 on a blocking finding.

Reviewed forWhich subcommands read as nouns, or which flags name something other than their mode or value? Look at the commands and flags the change adds.

Marked guidance: a reviewer answers this question.