IF Commons GitHub

The ontology in TypeScript

0012Draft

0012-ontology · owner if · domain commons

The RDF library

FR-001reviewno test run

The kernel MUST take RDF as typed values (branded IRIs, namespaces, named nodes, literals, triples and quads) from the library rdf (@intellectual-frontiers/rdf, rdf 0001-rdf FR-001), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT hold it itself.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library rdf: rdf 0001-rdf FR-001

Cited by: RDF, rdf-term

FR-002reviewno test run

The kernel MUST take typed vocabularies and the way to make one from the library rdf (@intellectual-frontiers/rdf, rdf 0001-rdf FR-002), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT hold it itself.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library rdf: rdf 0001-rdf FR-002

Cited by: RDF, rdf-term, rdf-vocabularies

FR-003reviewno test run

The kernel MUST take class schemas and the individuals they make from the library rdf (@intellectual-frontiers/rdf, rdf 0001-rdf FR-003), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT hold it itself.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library rdf: rdf 0001-rdf FR-003

Cited by: RDF, rdf-schema

FR-004reviewno test run

The kernel MUST take the schemas an ontology states about itself, code lists and SKOS schemes from the library rdf (@intellectual-frontiers/rdf, rdf 0001-rdf FR-004), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT hold it itself.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library rdf: rdf 0001-rdf FR-004

FR-005reviewno test run

The kernel MUST take the checks a type cannot state from the library rdf (@intellectual-frontiers/rdf, rdf 0001-rdf FR-005), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT hold it itself.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library rdf: rdf 0001-rdf FR-005

Cited by: RDF, rdf-schema

FR-006reviewno test run

The kernel MUST take the writers of N-Triples, N-Quads, canonical Turtle and JSON-LD from the library rdf (@intellectual-frontiers/rdf, rdf 0001-rdf FR-006), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT hold it itself.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library rdf: rdf 0001-rdf FR-006

Cited by: RDF, rdf-write, Mizan, the IF Spec Profile

FR-007reviewno test run

The kernel MUST take that it reads no syntax from the library rdf (@intellectual-frontiers/rdf, rdf 0001-rdf FR-007), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT hold it itself.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library rdf: rdf 0001-rdf FR-007

Cited by: integrations/pure/read-json-ld, integrations/pure/read-rdf, RDF, rdf-write, IFC Mizan Integrations

Commons' ontology

FR-008checkpassing

Commons' ontology MUST be TypeScript modules under commons/ontology/ that import nothing but the kernel's RDF and one another, one module for each file of facts, each exporting its individuals and the file they make (its name, its prefixes and its individuals), and a mod.ts for each ontology that lists its files. A module generated by an import (*.auto.ts, 0019-mizan-integrations FR-006) MAY stand beside them: it states a typed vocabulary of a standard's terms, imports nothing but the kernel's RDF, carries its header (its source, license and SHA-256) and is not a file of facts. No .ttl file MAY be under commons/ontology/: Turtle is not a source.

Enforced (check): .github: bun test ./tests/ — Ontology: the modules import only the kernel's RDF and one another, list their files, and no .ttl is under commons/ontology

Proved by: tests/commons-packaging.test.ts

Tests: passed: tests/commons-packaging.test.ts Ontology: the modules import only the kernel's RDF and one another, mod.ts lists every fil

Cited by: audit/mod, ifccm/mod, ifqs/mod, ifr/mod, Ontology, kanon/mod, mizan/mod, oto/mod, planning/mod, supply-chain/packaging/mod, Packaging

FR-009checkpassing

Every IRI of the ontology MUST be made from a namespace or a typed vocabulary (FR-001, FR-002), never written as free text (the address of a download that pm:downloadUrl holds is a value of a term, not an IRI of the ontology, and is written where it is stated; amended 2026-11-20); every class and property MUST be stated by the schemas of FR-004, every individual by a class schema of its ontology's vocabulary module, and every code list (the packaging operations, support statuses, assurances, manager kinds and tiers) by a code list of FR-004, whose keys the tools map to their words in a table the compiler holds complete.

Enforced (check): .github: bun test ./tests/ — Ontology: no IRI is written as free text in a module; the code lists are the tools' unions

Proved by: tests/commons-packaging.test.ts

Tests: passed: tests/commons-packaging.test.ts Ontology: no IRI is written as free text, and the code lists are the tools' unions

Cited by: supply-chain/packaging/packaging

FR-010checkpassing

The type checker MUST refuse an ontology module with a required field left out, a value of the wrong range or a reference to an individual of another class: tsc (TypeScript 7) over the generator, which imports the ontology, fails, and the tests check it on copies of the ontology. What a type cannot state (the kernel's checks of FR-005, an empty text, an identifier used twice, a reference to an individual no module states, and the rules of 0002-packaging FR-004 to FR-008, 0002-packaging FR-014 and 0004-rules FR-002) MUST be found by the generator before it writes anything, as 0002-packaging FR-010 says.

Enforced (check): .github: bun test ./tests/ — Ontology: tsc 7 refuses copies with a missing field, a wrong range and a wrong class; Generator: the rules a type cannot state are named and nothing is written

Proved by: tests/commons-packaging.test.ts

Tests: passed: tests/commons-packaging.test.ts Ontology: the type checker refuses a missing field, a value of the wrong range and an indi

FR-011checkpassing

The generator MUST write the packaging ontology as commons/generated/packaging.auto.ttl, in the canonical Turtle of FR-006, beginning with lines that say it is generated, by commons/tools/generate-packaging.ts, from which modules, and not to be edited; and its --check MUST fail where the file is not what the modules make (0001-software-supply-chain FR-002). Turtle is committed because it is the form an RDF tool and a person reviewing a change of meaning read; N-Triples and JSON-LD are not committed, since the kernel writes them from the same values for whoever needs them.

Enforced (check): .github: bun test ./tests/ — Generator: packaging.auto.ttl is what the modules make, says its generator and is the same bytes twice

Proved by: tests/commons-packaging.test.ts

Tests: passed: tests/commons-packaging.test.ts Ontology: the Turtle export says it is generated and by what, and holds every triple once

Cited by: generate-ontology, Libraries, Packaging

FR-012checkpassing

The source_sha256 the generated tables carry (0002-packaging FR-011) MUST be the SHA-256 of the canonical N-Triples (FR-006) of the whole ontology, so that a change of a fact changes it and a change of layout or comments does not.

Enforced (check): .github: bun test ./tests/ — Ontology: source_sha256 is the SHA-256 of the canonical N-Triples, and a comment changes no generated file

Proved by: tests/commons-packaging.test.ts

Tests: passed: tests/commons-packaging.test.ts Ontology: source_sha256 is the SHA-256 of the canonical N-Triples, and a change of a comme

Cited by: generate-ontology, Packaging

FR-013noneno test run

A file of the ontology converted from Turtle MUST keep every triple: the graph its module makes MUST be the graph of the Turtle it was taken from (a literal with no datatype being an xsd:string), compared triple by triple when it is converted.

Enforced (none): a one-time comparison when the Turtle was converted (7 files, 2874 triples, reported in the commit that converted it); the Turtle it was compared with is deleted in that commit

Cited by: IFC Mizan Integrations

FR-014checkpassing

Every class and property of an ontology MUST have a record of its basis, adopts, specializes, maps or unaligned (0018-standards-first FR-003), as an mz:OntologyTerm in an audit of that ontology (commons/ontology/audit/, commons/ontology/mizan/ for Mizan's own); a term with no record MUST fail the check of commons/libraries/src/check.ts whatever its baseline holds. A record whose basis is maps or specializes MUST name the standard's term, and a term it names MUST be one of a pinned import (0019-mizan-integrations), so that a mapping to a term the import does not hold does not compile.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan.test.ts: a term with no record is found and fails whatever the baseline holds; every term of the packaging ontology and of Mizan's vocabulary has a record; the mappings name terms of the pinned schema.org import (the compiler)

Proved by: mizan/suite/mizan.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's mapping names a standard term, and an unaligned term of the audit says why and wh

Cited by: standards, audit/packaging, Ontology, mizan/mizan

FR-015checkpassing

A code list MUST be able to hold thousands of entries: the cost of type-checking one is linear in its entries (measured on 2026-11-17 with TypeScript 7: 5,000 entries checked in 0.18 s and 85 MB, against 0.03 s and 55 MB for none), and a test MUST find that a code list of 5,000 entries type-checks, with a key type of its entries, within 30 seconds.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan.test.ts: a code list of 5,000 entries is written to a folder and tsc 7 checks it, with its key type, within 30 seconds

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

Tests: passed: suite/mizan.test.ts a code list of 5,000 entries type-checks with a key type of its entries, within 30 seconds

FR-016checkpassing

An ontology of commons that is published as Turtle MUST name its version, owl:versionInfo and owl:versionIRI (the ontology's IRI and the version, https://www.intellectualfrontiers.com/ontology/mizan/1.0.0), the version being a Semantic Version (0026-works-versioning FR-015), so that a consumer outside TypeScript can pin the version it read; the kernel's OwlOntology schema MUST give the version IRI as an optional field.

Enforced (check): .github: bun test ./tests/ — tests/commons-mizan-ontology.test.ts: the generated Turtle names owl:versionInfo and owl:versionIRI; rdflib reads the version IRI back; mizan.test.ts: the kernel's OwlOntology takes a version IRI

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

Tests: passed: suite/mizan.test.ts the kernel's OwlOntology takes a version IRI, which the Turtle writes as owl:versionIRI

Out of scope

  • Reading RDF, querying it and comparing graphs with blank nodes (a harness that needs them uses an RDF store of its own, as erga uses Oxigraph).
  • SHACL shapes made from the class schemas, and OWL axioms beyond what the ontology states.
  • Showing the ontology on the documentation site (commons 0011-documentation).
  • The vocabularies of a harness or a company (erga's ifo:, ifid: and the rest): they stay in their own repositories.

Edge cases

  • A family whose usesManager names a value that is not a manager (a platform): the type checker fails, per FR-003 and FR-010.
  • A pin whose version field is left out: the type checker fails; one whose version is an empty text: the generator names it, per FR-010.
  • A family that names, by its IRI, a manager no module states: it compiles, and the generator names it, per FR-010.
  • An order of 1.5: the kernel names it as not an integer, per FR-005.
  • A rule whose set is installers: the type checker fails, as the set is one of a list of words; run without the checker, the kernel and the generator name it, per FR-003, FR-005 and FR-010.
  • Two modules that state the same subject: the kernel names it, per FR-005.
  • parseIri("relative/path") or an IRI holding a space: an error, never an IRI, per FR-001.
  • The same individuals stated in another order: the same Turtle, N-Triples and JSON-LD bytes, per FR-006.
  • A string with a quote, a backslash, a new line or a control character: escaped in Turtle and N-Triples, per FR-006.
  • A .ttl file added under commons/ontology/: a test names it, per FR-008.
  • packaging.auto.ttl edited by hand: --check fails, per FR-011.
  • A module's comments changed and no fact: source_sha256 and every generated file stay the same, per FR-012.

Assumptions

  • TypeScript 7 checks the generator, the ontology and the kernel with one set of options, so they agree on the kernel's types.
  • The ontology is small enough (a few thousand triples) that it is held in memory and written at once.

Open questions

OQ-1open question

Whether the class schemas should also give SHACL shapes, as erga's do, once a harness validates data that does not come from TypeScript.

OQ-2open question

Whether other harnesses' ontologies (erga's) move onto the kernel's RDF, and which of erga's DSL (blank nodes as values, lists) the kernel then gives.

Key entities

  • IRI - an absolute IRI, branded once checked.
  • Namespace - a prefix and its IRI, which makes the terms of a vocabulary.
  • Named node - a term, branded with the classes it is an individual of.
  • Class schema - a class and its fields, from which an individual's type and triples come.
  • Individual - a named node with its values, made by a class schema.
  • Code list - the individuals of one class keyed by local name, a union type.
  • Ontology file - a module's name, prefixes and individuals.

Success criteria

SC-001success criterion

A reference to an individual of the wrong class, a missing field or a misspelt term fails tsc.

SC-002success criterion

The generator reads no Turtle, and every generated table is what it was before the conversion except for the source hash and the name of the source in its first line.

SC-003success criterion

Commons has no RDF writer outside the kernel.

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
  • [x] Confidential: no sensitive fact written as a literal

Cited by

generate-ontology, Libraries, Mizan, integrations/pure/export-html, integrations/pure/read-json-ld, integrations/pure/read-rdf, standards, audit/mod, audit/packaging, ifccm/mod, ifqs/mod, ifr/mod, Ontology, kanon/mod, mizan/mizan, mizan/mod, oto/mod, planning/mod, supply-chain/packaging/mod, supply-chain/packaging/packaging, RDF, rdf-schema, rdf-term, rdf-vocabularies, rdf-write, Intellectual Frontiers Commons, Ontology, Libraries, The ontologies of commons, Packaging, Mizan, the IF Spec Profile, The ladder, IFC Mizan Integrations, How works are versioned, Kanon

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