IF Commons GitHub

Standards first

0018Draft

0018-standards-first · owner if · domain commons · part of 0003-mizan

The order

FR-001noneno test run

A specification or an ontology MUST NOT coin a term, a schema or a vocabulary where a standard names it, and MUST take it, from the first of these that has it: law (a United States federal law or regulation, and a state or local law that applies); United States and NIST standards; ISO standards; broadly used vocabularies (schema.org, Dublin Core, SKOS, PROV, SPDX and their like); then state and local standards that are not law, where they do not conflict with the sources above them.

Enforced (none): Planned, Phase 2 and 3 of issue #10: the basis fields and the standards rules are not built yet

Cited by: Mizan, spec-terms, Kanon

FR-002noneno test run

A term taken from law MUST keep the law's own wording as its label, carry the law's definition as its skos:definition and cite the law (FR-008), and MUST NOT be paraphrased; where laws differ by jurisdiction, each MUST be its own jurisdiction-qualified individual, never one merged coined term.

Enforced (none): Planned, Phase 2 and 3 of issue #10: the basis fields and the standards rules are not built yet

Cited by: mizan/mizan

The basis of a term

FR-003checkpassing

Every class, property, individual and code list of an ontology MUST carry a basis: adopts (it is the standard's own term, by its IRI), specializes (a subclass or subproperty of one), maps (it has a mapping, such as skos:exactMatch, to one) or unaligned (no standard names it). A term with no basis MUST fail to compile.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan.test.ts: a term on a standard that names none is found; every class of Mizan's vocabulary has a basis (tests/commons-mizan-ontology.test.ts). Required by the compiler for Mizan's OntologyTerm only: the kernel's schemas do not yet require it (0012 FR-014)

Proved by: mizan/suite/mizan.test.ts, ontology/suite/ifccm-ontology.test.ts, ontology/suite/ifqs-ontology.test.ts, tests/commons-mizan-ontology.test.ts

Tests: passed: suite/mizan.test.ts a term of an ontology with no record of its basis is found, and every term of the packagin; passed: suite/mizan.test.ts a term on a standard must name its term, and an unaligned term must say why; passed: suite/ifccm-ontology.test.ts every class of IFCCM's vocabulary, and the class of every code list, has an individual say; passed: suite/ifqs-ontology.test.ts every class of IFQS's vocabulary, and the class of every code list, has an individual sayi; passed: tests/commons-mizan-ontology.test.ts every class of Mizan's vocabulary has an individual saying its basis

Cited by: check, harness, Mizan, integrations/pure/import-vocabulary, standards, audit/packaging, ifccm/ifccm, ifqs/ifqs, ifr/audit, Ontology, kanon/kanon, mizan/mizan, The Operational Truth Ontology, Intellectual Frontiers Workspaces, Mizan, the IF Spec Profile, The Planning ontology, Intellectual Frontiers Capabilities Configuration Management, How works are versioned, Kanon, Planning

FR-004checkpassing

An unaligned term MUST carry a justification, the standards looked at and why none fits, and MUST be counted: the count of unaligned terms is the measure of drift, and the baseline of them only shrinks.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan.test.ts: an unaligned term with no justification is found, and the findings are held by the baseline that only shrinks

Proved by: mizan/suite/mizan.test.ts, ontology/suite/ifccm-ontology.test.ts, ontology/suite/ifqs-ontology.test.ts, tests/commons-mizan-ontology.test.ts

Tests: passed: suite/mizan.test.ts a term on a standard must name its term, and an unaligned term must say why; passed: suite/ifccm-ontology.test.ts an unaligned class carries its justification, the standards examined, and the day it was a; passed: suite/ifqs-ontology.test.ts an unaligned class carries its justification, the standards examined, and the day it was a; passed: tests/commons-mizan-ontology.test.ts an unaligned term carries a justification and its date, and a term with a standard names i

FR-005checkpassing

An unaligned term MUST be recorded by a Decision, an individual of the ontology that a harness MAY link to its own record of the decision. The Decision MUST exist within 90 days of the commit that adds the term; within the 90 days its absence is a finding in the baseline, and after it the check fails.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan.test.ts: a decision is missing within 90 days (held by the baseline) and overdue after, which fails whatever the baseline holds; run on commons' own folder; ontology-decisions.test.ts: the twelve terms kept unaligned by the owner's decision of 2026-11-17 each have a Decision that names them, and reach the Turtle

Proved by: mizan/suite/mizan.test.ts, ontology/suite/ontology-decisions.test.ts

Tests: passed: suite/mizan.test.ts a decision is due 90 days after the term: missing within them, overdue after, and none whe; passed: suite/mizan.test.ts commons' own folder holds Mizan's terms: the baseline holds the missing decisions within 9; passed: suite/ontology-decisions.test.ts six unaligned terms are kept so by the owner's decision of 2026-11-17: each has a Decision; passed: suite/ontology-decisions.test.ts the Decisions of the six terms are individuals of the generated Turtle, each with its day

Cited by: check, harness, Mizan, standards, audit/packaging, ifr/audit, Ontology, mizan/mizan, Intellectual Frontiers Workspaces, Kanon, Archon, Distribution

Authority and standards as data

FR-006checkno test run

A standard MUST be a typed Standard of the ontology: its issuer, name, version, location, license (an SPDX identifier) and the SHA-256 of what was imported; a newer version of a standard than the pin MUST be a finding (FR-014).

Enforced (check): .github: cd commons/libraries && bun test suite/ — mizan-newer.test.ts: a newer version than the pin is a finding (FR-014); a Standard's fields are decoded by the importer (mizan-integrations.test.ts)

Cited by: governance/exchange, governance/ids, Libraries, newer, integrations/pure/types, Integrations governance, Licensing

FR-007noneno test run

A specification MUST copy only what a standard's license permits: a standard that cannot be redistributed (an ISO standard) is cited by its identifier and clause, never copied.

Enforced (none): Planned, Phase 2 and 3 of issue #10: the basis fields and the standards rules are not built yet

Cited by: Intellectual Frontiers Capabilities Configuration Management, Intellectual Frontiers Quality System, Licensing

FR-008checkpassing

A requirement that comes from law MUST cite its authority as typed data (an Authority: the law's title, part and section as its jurisdiction writes them), in the form FR-015 gives.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-authority.test.ts: a requirement that names a law and no Authority is found, and commons' own specifications pass (FR-015, FR-016)

Proved by: mizan/suite/mizan-authority.test.ts, tests/commons-mizan-ontology.test.ts

Tests: passed: suite/mizan-authority.test.ts commons' own specifications read for real: every requirement that names a law cites its au; passed: tests/commons-mizan-ontology.test.ts the laws of the first domains are authorities, and the QMSR took effect on 2 February 2026

FR-009checkpassing

A feature's plan.md MUST have a section, Standards considered, naming the standards looked at and the one chosen.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan.test.ts: a plan with no Standards considered section named

Proved by: mizan/suite/mizan.test.ts

Tests: passed: suite/mizan.test.ts a plan with no Standards considered section is named, and one with it, or no plan, is not

Cited by: check, Libraries, Mizan, rules, Mizan, the IF Spec Profile

Reach

FR-010nonepassing

The first domains are federal security (NIST publications, OSCAL and FedRAMP baselines), FDA's QMSR (21 CFR Part 820, incorporating ISO 13485:2016) and 21 CFR Part 11 (electronic records and signatures). A domain MUST be pulled up into commons when more than one harness should read the same facts. Authority: mzid:authority-21-cfr-820, mzid:authority-21-cfr-11.

Enforced (none): Planned, Phase 2 and 3 of issue #10: the basis fields and the standards rules are not built yet

Proved by: tests/commons-mizan-ontology.test.ts

Tests: passed: tests/commons-mizan-ontology.test.ts the laws of the first domains are authorities, and the QMSR took effect on 2 February 2026

Cited by: ifccm/ifccm

FR-011noneno test run

Mizan's own formats MUST follow this order: requirements are worded in RFC 2119 keywords and EARS patterns, scenarios in Gherkin's Given, When, Then, mappings in SSSOM, provenance in PROV-O, catalogs in DCAT and licenses as SPDX identifiers.

Enforced (none): Planned, Phase 2 and 3 of issue #10: the basis fields and the standards rules are not built yet

FR-012noneno test run

The rules of this specification MUST be delivered as warnings with a baseline that only shrinks (a new finding fails, and a line of the baseline that no longer occurs fails), never as a first-day failure of what a harness already holds.

Enforced (none): Planned, Phase 2 and 3 of issue #10: the basis fields and the standards rules are not built yet

Cited by: Intellectual Frontiers Capabilities Configuration Management

FR-013checkpassing

A term MAY be deprecated, with the day (mz:deprecatedOn) and the term that replaces it (mz:replacedBy); a deprecated term with no replacement, and a specification that names a deprecated term, MUST be found as findings the baseline may hold.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan.test.ts: a deprecated term with no replacement is found, and a specification naming a deprecated term is found saying what replaces it

Proved by: mizan/suite/mizan.test.ts

Tests: passed: suite/mizan.test.ts a deprecated term with no replacement is found, and a specification that names a deprecate

Checking the pins and the authorities

FR-014checkpassing

WHEN commons/libraries/src/newer.ts runs, it MUST read each manifest (*.import.ts) of the folder it is given (default commons/libraries/src/imports/) that names a latest source, an https:// URL that always serves the newest version of the standard (http:// on the loopback address for a test), fetch it once, and give one finding, mizan/standard-newer, for each whose SHA-256 differs from the manifest's pin, as one sentence that names the standard, its pinned version, the URL and the two hashes. The SHA-256 is that of the text with its line ends normalised, as an import computes it (0019-mizan-integrations FR-014); a manifest with no latest is not read.

Enforced (check): .github: cd commons/libraries && bun test suite/ — mizan-newer.test.ts: a real local HTTP server serves the pinned bytes (no finding) and then other bytes (one finding with both hashes); a manifest with no latest is not read

Proved by: libraries/suite/mizan-newer.test.ts

Tests: passed: suite/mizan-newer.test.ts the command fetches each latest source from a real server: the pin's bytes are no finding,; passed: suite/mizan-newer.test.ts a standard whose latest source serves other bytes than its pin is one finding of one sente

Cited by: Libraries, newer

FR-015checkpassing

A requirement that comes from law MUST cite its authority in this form: its text carries Authority: followed by one or more identifiers of typed mz:Authority individuals of the ontology (such as mzid:authority-21-cfr-820), separated by commas. A requirement whose text names a citation of the Code of Federal Regulations (a title, CFR and a part or section) or of the United States Code (a title, U.S.C. and a section) is taken to come from law; each such citation MUST be covered by one of the authorities the requirement names, that is, its text after the title's number and the words Part or § MUST begin with the authority's own citation, up to a part, a section or a hyphen. A requirement that names a law and does not come from it MUST be worded so that it names none. An authority a harness names MUST be one of the individuals the harness gives the rule.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-authority.test.ts: the convention, what a citation of law is, and the covering of a citation by an authority, each in both directions

Proved by: mizan/suite/mizan-authority.test.ts

Tests: passed: suite/mizan-authority.test.ts a citation of the Code of Federal Regulations or the United States Code is read however it; passed: suite/mizan-authority.test.ts a harness gives the rule its own authorities, and only those are known to it; passed: suite/mizan-authority.test.ts an authority covers its own citation and what is under it, and nothing whose number only s; passed: suite/mizan-authority.test.ts commons' ontology gives the authorities of 21 CFR Part 820 and Part 11 and, for consumer p

Cited by: rules, Subject profiles

FR-016checkpassing

commons/mizan/src/rules.ts MUST deliver FR-015 as a plugin, mizan/authority-citation (0003-mizan FR-019), that finds a requirement that names a citation of law and carries no Authority:, a requirement whose Authority: names an identifier that is no mz:Authority individual, and a citation no named authority covers, one finding for each, as a warning held by the baseline (FR-012).

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-authority.test.ts: the three findings of mizan/authority-citation, and commons' own specifications read for real

Proved by: mizan/suite/mizan-authority.test.ts

Tests: passed: suite/mizan-authority.test.ts commons' own specifications read for real: every requirement that names a law cites its au; passed: suite/mizan-authority.test.ts a requirement that names a law and no authority, one that names an authority there is not,; passed: suite/mizan-authority.test.ts the finding is a warning held by the baseline: it fails when new, is held once written, an; passed: suite/mizan-authority.test.ts the message of each finding says what is wrong in one sentence

Cited by: Mizan, rules

FR-017checkpassing

newer.ts MUST hold its findings against mizan.newer.baseline.txt beside the folder's mizan.baseline.txt, judged as check.ts judges its own (a finding the baseline does not hold fails, and a line that no longer occurs fails, and --write-baseline writes it), MUST exit 2 and name the URL where a latest source cannot be fetched, and MUST be opt-in: check.ts and import.ts --check MUST NOT use the network, so that the network never fails the offline check.

Enforced (check): .github: cd commons/libraries && bun test suite/ — mizan-newer.test.ts: the baseline holds a finding and goes stale when it is fixed, a URL that cannot be fetched exits 2 naming it, and check.ts and import.ts --check run with the network unreachable

Proved by: libraries/suite/mizan-newer.test.ts

Tests: passed: suite/mizan-newer.test.ts the command fetches each latest source from a real server: the pin's bytes are no finding,; passed: suite/mizan-newer.test.ts a latest source that cannot be fetched exits 2 and is named, and is neither a pass nor a f; passed: suite/mizan-newer.test.ts the offline checks do not use the network: check.ts and import.ts --check pass with every

Cited by: Libraries, newer, Intellectual Frontiers Capabilities Configuration Management

Out of scope

  • Importing a standard into TypeScript and exporting ours: 0019-mizan-integrations.
  • Which law applies to a given product: the product's own specifications cite their authority.

Edge cases

  • A term for a medical device's complaint file: its wording and definition come from 21 CFR Part 820 as amended by the QMSR and ISO 13485:2016 is cited and not copied, per FR-001, FR-002 and FR-007.
  • A state privacy law whose definition differs from a federal one: two individuals, each qualified by its jurisdiction, per FR-002.
  • A class that specializes schema:SoftwareApplication: basis specializes, per FR-003.
  • A term deprecated in favour of another, named by a specification: found, saying what replaces it, per FR-013.
  • A term deprecated with no replacement: found, per FR-013.
  • A term added to the packaging ontology with no record in its audit: the check fails, whatever the baseline holds, per FR-003.
  • A new unaligned term with no Decision on day 30: a finding in the baseline, not a failure, per FR-005.
  • The same term on day 91: the check fails, per FR-005.
  • A newer NIST publication than the pinned version: a stale-pin finding, per FR-006.
  • A manifest whose latest URL now serves other bytes than the pin: one finding, with both hashes, per FR-014.
  • A manifest whose latest URL serves the bytes of the pin: no finding, per FR-014.
  • A latest URL that cannot be fetched: exit 2 naming it, never a pass, and the offline check is not affected, per FR-017.
  • A requirement that names section 820.30 of 21 CFR and carries Authority: mzid:authority-21-cfr-820 (whose citation is 21 CFR Part 820): not found, because the part covers its sections, per FR-015.
  • A requirement that names part 8200 of 21 CFR under that authority: found, because 8200 does not begin with 820 at a boundary, per FR-015 and FR-016.
  • A requirement that names Part 11 of 21 CFR and carries no Authority:: found, per FR-015 and FR-016.
  • A requirement whose Authority: names mzid:authority-nothing, or an authority that does not cover the citation it names: found, per FR-016.
  • A specification of a feature whose plan.md names no standards: a warning and a baseline entry, per FR-009 and FR-012.

Assumptions

  • The FDA's QSR (21 CFR Part 820) has been replaced by the QMSR, which incorporates ISO 13485:2016 by reference and took effect on 2 February 2026; Phase 0 of issue #10 verifies this, and the Authority records are written from the verified text.
  • A requirement checked by the plan.md rule is one of a feature built with Spec Kit's plan template.

Open questions

OQ-1open question

Which OSCAL models and version the proof register maps to (0003-mizan FR-011), settled in Phase 0 of issue #10.

OQ-2open question

Whether the Decision's 90 days are counted from the commit's date or from the date it first reaches main.

Key entities

  • Standard - a pinned, licensed, hashed standard.
  • Authority - a typed citation of a law or regulation.
  • Jurisdiction - the federal, state or local body whose law it is.
  • Basis - how a term relates to a standard: adopts, specializes, maps or is unaligned.
  • Decision - the record of why a term is unaligned.

Success criteria

SC-001success criterion

Every term of the ontology has a basis, and the count of unaligned terms is reported and never rises.

SC-002success criterion

Every requirement that comes from law cites its authority.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

governance/kinds, governance/exchange, governance/ids, check, Libraries, newer, harness, Mizan, integrations/pure/import-vocabulary, integrations/pure/types, rules, spec-terms, standards, audit/mod, audit/packaging, ifccm/ifccm, ifqs/ifqs, ifr/audit, ifr/mod, Ontology, kanon/kanon, mizan/mizan, mizan/mod, The layers of GRC, The harness of Mizan, Libraries, Integrations governance, The Operational Truth Ontology, Intellectual Frontiers Workspaces, Mizan, the IF Spec Profile, The Planning ontology, Intellectual Frontiers Capabilities Configuration Management, Intellectual Frontiers Quality System, How works are versioned, Conformance levels, Subject profiles, Kanon, Archon, Licensing, Distribution, Planning

Titles, headings, exports, tables, columns and requirements. Esc closes.