Browse pages
Record Identifiers
Every record carries one identifier naming its type, home, and name.
Intent#
Every record carries one identifier naming its type, home, and name. One form per type lets a reader find the record from the identifier alone, by reading or by searching.
Concepts#
Forms per record type#
| Type | Form | Example |
|---|---|---|
product | product/<name> | product/clinic-booking |
constraint | constraint/<name> | constraint/clinic-data-retention-law |
research | research/<name> | research/late-fee-benchmarks |
decision | decision/<number>-<name> | decision/0047-extend-loan-period |
requirement | requirement/<topic>.<name> | requirement/fees.flat-late-fee |
problem | problem/<name> | problem/overdue-books-block-holds |
feature | feature/<name> | feature/hold-queue |
actor | actor/<name> | actor/borrower |
role | role/<name> | role/librarian |
permission | permission/<name> | permission/manage-hold |
journey | journey/<name> | journey/borrow-a-book |
module | module/<name> | module/loans |
business-record | business-record/<module>.<name> | business-record/loans.book-loan |
rule | rule/<home>.<name> | rule/book-loan.only-an-active-loan-renews |
use-case | use-case/<module>.<name> | use-case/loans.renew-loan |
result | result/<use-case-name>.<name> | result/renew-loan.loan-not-active |
case | case/<use-case-name>.<name> | case/renew-loan.renewing-twice-is-refused |
event | event/<business-record-name>.<past-tense> | event/book-loan.loan-renewed |
entry-point | entry-point/<name> | entry-point/admin |
limit | limit/<name> | limit/holds-per-borrower |
runbook | runbook/<name> | runbook/restore-a-backup |
standard | standard/<home>.<name> | standard/review.two-reviewers-per-change |
exception | exception/<name> | exception/single-reviewer-hotfix |
known-gap | known-gap/<name> | known-gap/renewal-cases-unproved |
term | term/<name> | term/borrower |
A rule home is a business record name or a module name. A project standard home is the rule page stem holding it.
Name rules#
A name follows these rules:
- Write one to six lowercase words joined by hyphens.
- Place digits inside a word, never as the whole name.
- Count the decision number as a word.
- Keep a use case name unique across the project.
- Keep the negation in a rule name when its statement negates.
- Let a person choose the name; no tool strips words into one.
Wire codes#
Wire codes are not identifiers and never change shape: failure codes such as failure/orders.not_found, audit action codes, and permission codes in code.
Resolution#
Every citation of an identifier resolves to a written record. Unresolved citations fail the check.
Shared provisions keep their published litespec/<page>#<slug> form.
Standards#
Follow the identifier form of each record type#
rulecheckableRequirement A record identifier MUST follow the form its type row names.
Rationale One form per type lets a reader name the type and home from the identifier alone.
Example event/book-loan.loan-renewed names an event of the book loan record.
Name records with one to six words#
rulecheckableRequirement A name MUST carry one to six lowercase hyphenated words.
Rationale Short hyphenated names read aloud and stay stable across edits.
Example decision/0047-extend-loan-period counts its number as one word.
Keep use case names unique across the project#
rulecheckableRequirement A use case name MUST be unique across the project.
Rationale Results and cases belong to the use case named in their identifier, so a duplicate leaves that home unclear.
Keep business record names unique across the project#
rulecheckableRequirement A business record name MUST be unique across the project.
Rationale Rules and events take their home from the business record named in their identifier, so two records with one name leave that home unclear.
Keep negation in rule names#
rulecheckableRequirement A rule name MUST keep the negation its statement makes.
Rationale A reviewer reads the name as a true sentence without opening the statement.
Example A statement with never keeps never in its name.
Keep wire codes stable#
ruleguidanceRequirement A wire code MUST stay unchanged once clients read it.
Rationale Failure codes, audit action codes, and permission codes are not identifiers. Clients branch on their values, so a change breaks deployed readers.
Resolve every identifier citation#
rulecheckableRequirement Every identifier citation MUST resolve to a written record.
Rationale A citation naming nothing leaves the reader with no page to open.
Cite shared provisions in their published form#
rulecheckableRequirement A shared provision citation MUST use its published identifier.
Rationale Shared provisions keep their published form while project records use the type forms above.
Conventions#
None.
Reference example#
This informative example demonstrates litespec/backend/identifiers#follow-the-identifier-form-of-each-record-type and litespec/backend/identifiers#name-records-with-one-to-six-words.
An ordering system names one module, one record, one rule, and one use case with its results.
module/orders
business-record/orders.order
rule/order.only-paid-orders-ship
use-case/orders.place-order
result/place-order.order-placed
result/place-order.item-out-of-stockVerification#
| ID | Mark | Evidence |
|---|---|---|
| litespec/backend/identifiers#follow-the-identifier-form-of-each-record-type | checkable | litespec model check reports identifier-form. |
| litespec/backend/identifiers#name-records-with-one-to-six-words | checkable | litespec model check reports identifier-form. |
| litespec/backend/identifiers#keep-use-case-names-unique-across-the-project | checkable | litespec model check reports use-case-name-clash. |
| litespec/backend/identifiers#keep-business-record-names-unique-across-the-project | checkable | litespec model check reports business-record-name-clash. |
| litespec/backend/identifiers#keep-negation-in-rule-names | checkable | litespec model check reports rule-name-negation. |
| litespec/backend/identifiers#keep-wire-codes-stable | guidance | Do clients read the same code values as before? |
| litespec/backend/identifiers#resolve-every-identifier-citation | checkable | litespec model check reports reference-unresolved. |
| litespec/backend/identifiers#cite-shared-provisions-in-their-published-form | checkable | litespec validate emits no ID_UNKNOWN_REFERENCE diagnostic. |