IF Commons GitHub

IFC Mizan Integrations

0019Draft

0019-mizan-integrations · owner if · domain commons · part of 0003-mizan

The module

FR-001checkpassing

The module MUST live in commons/mizan/src/integrations/ and be exported as @intellectual-frontiers/mizan/integrations, in two layers: pure/, functions over text with no effect on the host, and host/, which fetches, reads and writes files and checks pins.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-boundaries.test.ts: pure/ imports only the kernel and itself, host/ exists, the module is exported

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

Tests: passed: suite/mizan-boundaries.test.ts the integrations module has a pure layer that imports only the foundation libraries and it

FR-002checkpassing

An integration MUST be a typed record: its id, its direction (import or export), the formats it reads and writes, the Standard it handles, and a run that returns a Result of its output or its findings; a registry MUST look integrations up by their formats. There MUST be no any and no non-null !, and a switch over a union MUST be exhaustive.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-integrations.test.ts: the registry looks integrations up by formats and refuses an identifier or a pair twice; the record is typed

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

Tests: passed: suite/mizan-integrations.test.ts a manifest with a field missing or of the wrong type is named once, with exit 2; passed: suite/mizan-integrations.test.ts the registry looks integrations up by their formats and refuses an identifier or a pair al

Cited by: Mizan, integrations/pure/registry, integrations/pure/types, mizan/mizan

FR-003noneno test run

Mizan's own checks (the requirement syntax, the standards-first rules) MUST be plugins through the same extension point, so that a harness can add its rules without a fork.

Enforced (none): Planned, Phase 4 of issue #10: the module is not built yet

FR-004checkpassing

The kernel MUST stay free of readers (0012-ontology FR-007); every reader of an RDF syntax or of a schema language MUST be in this module.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-integrations.test.ts: the reader reads the Turtle the kernel writes back to the same graph; kernel/rdf.test.ts: the kernel exports no reader

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

Tests: passed: suite/mizan-integrations.test.ts prefixes, a, lists, literals of every kind, long strings and comments are read; passed: suite/mizan-integrations.test.ts the reader reads the Turtle the kernel writes back to the graph the kernel's N-Triples say

Cited by: Mizan, integrations/pure/read-rdf

Import

FR-005checkpassing

An import MUST be made only where a term or schema a specification uses is not already available, and MUST name the slice it needs (a manifest of terms, with an optional closure), never a whole standard.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-integrations.test.ts: only the slice is taken, an empty slice and a term the source lacks are refused

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

Tests: passed: suite/mizan-integrations.test.ts a slice is imported as a typed vocabulary module whose header names its source, and the sa; passed: suite/mizan-integrations.test.ts a term the source lacks or does not type is named, an empty slice is refused, and a loss i

Cited by: Mizan, integrations/host/import, integrations/pure/import-json-schema, integrations/pure/import-oscal-catalog, integrations/pure/import-vocabulary

FR-006checkpassing

An import MUST refuse a source whose SHA-256 or license differs from its Standard record, and MUST write a generated .auto. TypeScript module (a typed vocabulary, class schemas and code lists) whose header names the source, version, hash, license and generator, and whose terms have the basis adopts.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-integrations.test.ts: a pin mismatch, no license and no right to copy are refused; the module's header names its source; the command writes and checks it

Proved by: mizan/suite/mizan-integrations-formats.test.ts, mizan/suite/mizan-integrations.test.ts

Tests: passed: suite/mizan-integrations-formats.test.ts a slice of $defs is imported as typed code lists and field-name unions, allOf and $ref fol; passed: suite/mizan-integrations-formats.test.ts a missing definition, one with nothing to hold, an empty slice, a pin mismatch, no license; passed: suite/mizan-integrations.test.ts a slice is imported as a typed vocabulary module whose header names its source, and the sa; passed: suite/mizan-integrations.test.ts the command imports from a manifest, checks the module is current, and the module it write; passed: suite/mizan-integrations.test.ts a source whose SHA-256 differs, a standard with no license and one that may not be copied

Cited by: Mizan, integrations/pure/import-json-schema, integrations/pure/import-oscal-catalog, integrations/pure/types, The ontology in TypeScript

FR-007checkpassing

An import MUST report what the typed form cannot hold (a blank node, an RDF list, a restriction) as a finding, and MUST NOT drop it silently.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-integrations.test.ts: a blank node and a collection are named as losses, in the slice only, and the rest is read

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

Tests: passed: suite/mizan-integrations.test.ts a term the source lacks or does not type is named, an empty slice is refused, and a loss i; passed: suite/mizan-integrations.test.ts a blank node value and a collection are named as losses, and the rest is still read; bad s

Cited by: Mizan, integrations/pure/read-rdf, integrations/pure/types

FR-008nonepassing

The graph a generated module writes, in canonical N-Triples, MUST equal the source's graph for the imported slice (0012-ontology FR-013).

Enforced (none): Planned, Phase 4 of issue #10: the module is not built yet

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

Tests: passed: suite/mizan-integrations.test.ts the command imports from a manifest, checks the module is current, and the module it write

FR-009checkpassing

Each import MUST leave its provenance as PROV-O Turtle beside its manifest (the module a prov:Entity generated by an import, a prov:Activity that used the source, a prov:Entity named by its SHA-256 with its title, publisher, version, location and license): what was imported, from where, by which generator and with which hash, and no date or host, so that the same import gives the same text.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-integrations.test.ts: the provenance is PROV-O Turtle the reader reads back, deterministic; the command writes it beside the manifest

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

Tests: passed: suite/mizan-integrations.test.ts an import leaves its provenance: a record, and PROV-O Turtle that the reader reads back

Cited by: Mizan, integrations/host/import, integrations/pure/import-json-schema, integrations/pure/import-oscal-catalog, integrations/pure/import-vocabulary, integrations/pure/provenance

Export

FR-010checkpassing

The module MUST write our ontology as Turtle, N-Triples, N-Quads and JSON-LD (the kernel's writers), and as SHACL shapes and JSON Schema (from class schemas), SKOS concept schemes (from code lists), SQL code-list tables, SSSOM mappings (from terms that name a standard's term and the relation to it, each justified as manual curation), an HTML view of an ontology (its classes, properties, code lists and the basis of each term, one self-contained page, so that it can be read without TypeScript), and OWL, RDF/XML and a DCAT entry for each published ontology (FR-016 to FR-019).

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-integrations.test.ts: SQL, SKOS, SHACL, JSON Schema and SSSOM written from a class schema, a code list and the mappings of terms; tests/commons-mizan-ontology.test.ts: Mizan's own exports are current. RDF/XML, OWL and DCAT: FR-016 to FR-019

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

Tests: passed: suite/mizan-integrations.test.ts a class schema is written as a JSON Schema (the one fields required, many an array, words ; passed: suite/mizan-integrations.test.ts a code list is written as a SKOS concept scheme that the reader reads back, one concept ea; passed: suite/mizan-integrations.test.ts a code list is written as a SQL table with its quotes escaped, and a table name that is no; passed: suite/mizan-integrations.test.ts mappings are written as an SSSOM TSV with its curie map, set id, license and justification; passed: suite/mizan.test.ts the HTML view escapes every text, says it is generated, and shows classes, properties, cod and 1 more

Cited by: generate-ontology, Libraries, publish-ontology, Mizan, integrations/pure/export-html, integrations/pure/export, integrations/pure/types, mizan/mizan, Mizan, the IF Spec Profile

FR-011checkpartly run

Each export MUST be read or checked by an independent tool in a test (an RDF parser for the RDF forms, a SHACL validator for shapes, a JSON Schema validator for schemas).

Enforced (check): .github: bun test ./tests/ — tests/commons-mizan-ontology.test.ts: rdflib parses the Turtle, pySHACL finds Mizan's ontology conforms to the shapes made from its schemas and rejects a broken one, jsonschema checks the JSON Schema; skipped where Python and these three are not installed (CI installs them, pinned)

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

Tests: skipped: tests/commons-mizan-ontology.test.ts independent tools read the exports: rdflib parses the Turtle, the RDF/XML (into the same g

FR-012noneno test run

The module MUST NOT publish anything to an outside project; where one of our terms could improve a standard, it MUST only prepare a proposal bundle for a person to decide on.

Enforced (none): Planned, Phase 4 of issue #10: the module is not built yet

Languages

FR-013noneno test run

The module's code MUST be TypeScript 7 where it can be, and the best stack for the job through a typed Exception where it cannot (0017-two-languages FR-003, FR-004); a TypeScript part MUST run on Bun and on Node 26, and an exception's tests run on the platforms it names.

Enforced (none): Planned, Phase 4 of issue #10: the module is not built yet

FR-014checkpassing

An import's source MAY be a URL (https://, or http:// on the loopback address for a test), fetched once and held to the SHA-256 pin of its manifest; the manifest names the version in the URL, never latest. --check MUST compare, offline, the manifest's pin and slice to the module's header and terms and the presence of the provenance file; with --fetch it MUST fetch the source and compare the module and the provenance fully, and it MUST exit 2, naming why, where the source cannot be fetched.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-integrations.test.ts: a source served over HTTP is written, checked offline, checked with a fetch, refused when its bytes change and named when it cannot be fetched

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

Tests: passed: suite/mizan-integrations.test.ts a source fetched from a URL is held to its pin: written, checked offline, checked with a f

Cited by: newer, integrations/host/import, Standards first

FR-015checkpassing

The module MUST import a slice of an OSCAL control catalog (NIST SP 800-53, FedRAMP baselines) from its JSON as a generated TypeScript module of a typed code list whose keys are the control identifiers (ac-2, ac-2.1), each with its title, its group and, for an enhancement, the control it enhances, and the type of those identifiers; the catalog's JSON MUST be read once into typed records, its title, version and OSCAL version MUST be in the module's header, and the refusals and the determinism of FR-006 apply. It MUST take identifiers and titles only, never the prose of a control, and a control the catalog lacks MUST be named.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-integrations.test.ts: a catalog read into typed controls, a slice imported deterministically, a missing control, a pin mismatch and no right to copy refused, the command run from a manifest with no namespace

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

Tests: passed: suite/mizan-integrations.test.ts a slice of controls is imported as a typed code list, deterministically, and a missing con; passed: suite/mizan-integrations.test.ts an OSCAL catalog is read into typed controls, enhancements included, and what is not a cat; passed: suite/mizan-integrations.test.ts the command imports an OSCAL catalog from a manifest with no namespace, and the module it

Cited by: Mizan, integrations/pure/import-oscal-catalog, Intellectual Frontiers Capabilities Configuration Management

FR-016checkpartly run

The module MUST write an ontology's triples as RDF/XML 1.1 in one canonical form (each subject once as an rdf:Description, rdf:type first and the other predicates by IRI, objects in the order of their N-Triples terms, the same bytes whatever the order the triples were stated in), such that an RDF/XML parser reads the same graph as the Turtle; what XML 1.0 cannot say (a predicate whose IRI has no XML name at its end, a control character in a literal) MUST be a finding and never silently changed.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-exporters.test.ts: the triples are written as canonical RDF/XML (the order of the statements does not matter, a plain string, a language, a datatype and a blank node are each written, text is escaped, a predicate with no XML name and a control character are named); tests/commons-mizan-ontology.test.ts: rdflib parses the RDF/XML into a graph isomorphic to the Turtle's, skipped where Python and rdflib are not installed

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

Tests: passed: suite/mizan-exporters.test.ts a namespace no declared prefix names gets ns1, ns2 in the order of its IRI, and a declared; passed: suite/mizan-exporters.test.ts triples are written as canonical RDF/XML: the order they were stated in does not matter, a; passed: suite/mizan-exporters.test.ts what XML cannot say is named, and never changed: a predicate with no XML name, a control c; skipped: tests/commons-mizan-ontology.test.ts independent tools read the exports: rdflib parses the Turtle, the RDF/XML (into the same g

Cited by: Mizan, integrations/pure/export-rdfxml

FR-017checkpartly run

The module MUST write an ontology's classes and properties as OWL 2 in functional syntax, deterministically: a declaration of each class, object property and data property (and of each class or datatype they name that the ontology does not define, and of each annotation property OWL 2 does not build in that is used), SubClassOf, the domain and the range of each property, and the annotations rdfs:label, rdfs:comment and skos:definition, with the ontology's label, description, version information and version IRI. It MUST state only what the typed schemas state (no restriction, disjointness or cardinality), and a datatype property whose range is a class, or an object property whose range is a datatype, MUST be a finding.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-exporters.test.ts: classes and properties are written as OWL functional syntax (declarations, SubClassOf, domain, range, annotations, the ontology's version IRI, the classes it names and does not define, the datatypes), deterministic, and a datatype range of an object property or a class range of a datatype property is named; tests/commons-mizan-ontology.test.ts: a reader written in the test checks the axioms against the Turtle graph (no OWL functional-syntax reader is a pinned dependency; the RDF/XML was also loaded once by hand into owlready2)

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

Tests: passed: suite/mizan-exporters.test.ts a datatype property with a class for a range, an object property with a datatype for a ran; passed: suite/mizan-exporters.test.ts classes and properties are written as OWL functional syntax, with their declarations, axio; passed: suite/mizan-exporters.test.ts the same ontology gives the same OWL whatever the order of its classes and properties, and; skipped: tests/commons-mizan-ontology.test.ts independent tools read the exports: rdflib parses the Turtle, the RDF/XML (into the same g

Cited by: Mizan, integrations/pure/export-owl

FR-018checkpartly run

The module MUST write a DCAT 3 catalog as Turtle for the ontologies a repository publishes: a dcat:Catalog of one dcat:Dataset for each ontology (title, description, its IRI as dcterms:identifier, dcat:version, dcterms:license, publisher), each with one dcat:Distribution for each generated file (title, dcat:mediaType and dcterms:format as the IANA media type's URI, dcat:downloadURL, dcat:accessURL, dcterms:license and, where a standard names the file's form, dcterms:conformsTo), with no date, so that the same catalog gives the same text; an IRI that does not parse and a media type that is not one MUST be findings.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-exporters.test.ts: the catalog is written as DCAT 3 Turtle (catalog, dataset, one distribution for each file with its media type, download URL and license), the same bytes for the same catalog, a bad IRI and a bad media type are named; tests/commons-mizan-ontology.test.ts: rdflib parses the catalog and finds the datasets and distributions, each distribution's file in the repository

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

Tests: passed: suite/mizan-exporters.test.ts the catalog is written as DCAT 3 Turtle: a catalog, a dataset for each ontology, a distrib; passed: suite/mizan-exporters.test.ts the same catalog gives the same text whatever the order of its datasets, and a bad IRI or ; skipped: tests/commons-mizan-ontology.test.ts independent tools read the exports: rdflib parses the Turtle, the RDF/XML (into the same g

Cited by: publish-ontology, Mizan, integrations/pure/export-dcat, Quality evidence, Trust

FR-019checkpassing

Mizan's generator (generate-ontology.ts) MUST write the RDF/XML, the OWL and the catalog of the Mizan ontology as commons/generated/mizan.auto.rdf, mizan.auto.ofn and mizan-catalog.auto.ttl, each saying it is generated, which --check MUST find current; the catalog MUST list the distribution of every file the generator writes for the ontology, and a refusal of an exporter (FR-016 to FR-018) MUST stop the run with exit 2, naming it.

Enforced (check): .github: bun test ./tests/ — tests/commons-mizan-ontology.test.ts: mizan.auto.rdf, mizan.auto.ofn and mizan-catalog.auto.ttl are what the generator makes, each says it is generated, the catalog lists a distribution for every file the generator writes for the ontology; textOf throws ExportRefused where an exporter refuses, which main turns into exit 2 (tested at textOf: the Mizan ontology itself is never refused, so the whole command has no failing case to run)

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

Tests: passed: tests/commons-mizan-ontology.test.ts the exports of the ontology (SHACL shapes, JSON Schema, SKOS, SQL, SSSOM mappings, RDF/XML; passed: tests/commons-mizan-ontology.test.ts the catalog lists a distribution of every file the generator writes for the Mizan ontology

Cited by: generate-ontology, Libraries, publish-ontology

Importers of JSON-LD, RDF/XML and JSON Schema

FR-020checkpartly run

The module MUST read JSON-LD, in its expanded and its compacted form with an inline @context, into the same triples the Turtle reader gives: @id, @type, @graph and @included, the terms of a context given as an IRI, a compact IRI or an object (@id, @type, @language, @container, @reverse), @vocab, @base and @language, aliases of keywords, language-tagged and typed values (numbers and booleans as typed literals, a number's text deciding xsd:integer or xsd:double), @list, @reverse and nested node objects (blank nodes where there is no @id). Its JSON MUST be read once, by a reader that keeps each number's text and each object's line.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-integrations-formats.test.ts: compacted and expanded JSON-LD read with vocab, base, aliases, coerced and typed values, a list, a reverse, a nested node and the text of a number; tests/commons-mizan-importers.test.ts: the graph equals rdflib's (skipped where Python is not installed)

Proved by: mizan/suite/mizan-integrations-formats.test.ts, tests/commons-mizan-importers.test.ts

Tests: passed: suite/mizan-integrations-formats.test.ts compacted JSON-LD with an inline context is read: vocab, base, aliases, coerced and typed ; passed: suite/mizan-integrations-formats.test.ts expanded JSON-LD, a top-level array and a language map are read; skipped: tests/commons-mizan-importers.test.ts the graph the JSON-LD reader gives equals the graph rdflib reads

Cited by: Mizan, integrations/pure/read-json-ld

FR-021checkpassing

The JSON-LD reader MUST name, with its line, each construct it cannot hold and MUST NOT drop it silently: a remote context (a string, which the pure layer does not fetch), @import, a scoped context, a named graph, @nest, a JSON literal, a container of @graph, @id or @type, and a key that expands to no IRI; the rest of the document is still read.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-integrations-formats.test.ts: a remote context, a scoped context, a named graph, a nest and a JSON literal are named with their line and the rest is read; bad JSON stops with its line

Proved by: mizan/suite/mizan-integrations-formats.test.ts

Tests: passed: suite/mizan-integrations-formats.test.ts what JSON-LD cannot hold is named with its line (a remote context, a named graph, a scoped

Cited by: Mizan, integrations/pure/read-json-ld

FR-022checkpassing

The module MUST import a slice of the $defs of a pinned JSON Schema (draft 2020-12) as a generated TypeScript module in which each enum, const or oneOf and anyOf of constants is a typed code list (a const tuple and the union type of its members) and each object's properties, its own and those of its allOf branches and the definitions they $ref, are a typed object keyed by field name (the field's type, whether it is required, what it refers to) with the union type of the field names; an enum or an object inside a property is lifted to a code list or fields of its own. The slice names definitions, never the whole schema, a definition the schema lacks MUST be named, the refusals, the header (which also names the slice and the schema), the provenance and the determinism of FR-006 and FR-009 apply, and a definition with no enum and no properties MUST end the import.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-integrations-formats.test.ts: a slice of $defs becomes code lists and field-name unions (allOf and $ref followed, enums lifted), deterministically, a missing definition and one with nothing to hold end the import; tests/commons-mizan-importers.test.ts: the lists and names agree with jsonschema and an independent resolution

Proved by: mizan/suite/mizan-integrations-formats.test.ts, tests/commons-mizan-importers.test.ts

Tests: passed: suite/mizan-integrations-formats.test.ts a slice of $defs is imported as typed code lists and field-name unions, allOf and $ref fol; passed: suite/mizan-integrations-formats.test.ts a missing definition, one with nothing to hold, an empty slice, a pin mismatch, no license; passed: tests/commons-mizan-importers.test.ts the code lists and field names a JSON Schema import writes agree with jsonschema and with

Cited by: Mizan, integrations/pure/import-json-schema

FR-023checkpassing

The JSON Schema importer MUST name, with the definition and the path it is in, what a typed union of names cannot hold, and MUST NOT drop it silently: composition other than allOf of objects and references and other than constants (anyOf, oneOf), patternProperties, additionalProperties as a schema, propertyNames, dependentSchemas, dependentRequired, if, not, unevaluatedProperties, a $ref that is not into the schema's $defs, a schema of another draft (read as 2020-12) and the value constraints (pattern, format, bounds and lengths). Annotations (title, description, default, examples) are prose a person reads in the schema and are not carried.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-integrations-formats.test.ts: additionalProperties as a schema, anyOf, value constraints, a $ref outside $defs, an earlier draft and a clash of identifiers are named

Proved by: mizan/suite/mizan-integrations-formats.test.ts

Tests: passed: suite/mizan-integrations-formats.test.ts a missing definition, one with nothing to hold, an empty slice, a pin mismatch, no license

Cited by: Mizan, integrations/pure/import-json-schema

FR-024checkpartly run

The module MUST read RDF/XML into the same triples, as hand-written TypeScript: node and property elements, rdf:about, rdf:ID, rdf:nodeID, anonymous nodes, rdf:resource, rdf:datatype, rdf:parseType Resource and Collection, property attributes, rdf:li, rdf:ID reification, xml:lang, xml:base and relative IRIs resolved against it (RFC 3986), and of XML the entities a <!DOCTYPE> internal subset declares, character references, CDATA, comments and namespaces. It MUST refuse what is not well-formed XML with the line.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-integrations-formats.test.ts: RDF/XML read with entities, base, rdf:ID, language, datatype, parseType, property attributes, rdf:li, CDATA and reification, and RFC 3986 resolution; tests/commons-mizan-importers.test.ts: the graph equals rdflib's. Twelve W3C RDF/XML files (8,848 triples) were also read to rdflib's graph while this was written, and are not copied here

Proved by: mizan/suite/mizan-integrations-formats.test.ts, tests/commons-mizan-importers.test.ts

Tests: passed: suite/mizan-integrations-formats.test.ts RDF/XML that is not well formed ends with its line, and an XML literal and an external ent; passed: suite/mizan-integrations-formats.test.ts RDF/XML is read: entities, base and relative IRIs, rdf:ID, language and datatype, parseTyp; passed: suite/mizan-integrations-formats.test.ts relative IRIs resolve as RFC 3986 says; skipped: tests/commons-mizan-importers.test.ts the graph the RDF/XML reader gives equals the graph rdflib reads

Cited by: Mizan, integrations/pure/read-rdf-xml

FR-025checkpassing

The RDF/XML reader MUST name, with its line, each construct it cannot hold and MUST NOT drop it silently: an XML literal (rdf:parseType="Literal" and the other parse types, whose canonical form it does not compute), an external or parameter entity, and an attribute with no namespace.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-integrations-formats.test.ts: an XML literal and an external entity are named and the rest is read; a document that is not well formed stops with its line

Proved by: mizan/suite/mizan-integrations-formats.test.ts

Tests: passed: suite/mizan-integrations-formats.test.ts RDF/XML that is not well formed ends with its line, and an XML literal and an external ent

Cited by: Mizan, integrations/pure/read-rdf-xml

FR-026checkpassing

The vocabulary importer MUST take its source in Turtle, N-Triples, JSON-LD or RDF/XML (the manifest's format is turtle, n-triples, json-ld or rdf-xml), with the checks, the findings and the determinism of FR-005 to FR-009 unchanged; a relative IRI of JSON-LD or RDF/XML resolves against the location the standard is published at.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-integrations-formats.test.ts: the same slice imported from JSON-LD and RDF/XML gives the same vocabulary, a blank-node value is named and a pin mismatch is refused; the command runs a json-ld and an rdf-xml manifest

Proved by: mizan/suite/mizan-integrations-formats.test.ts

Tests: passed: suite/mizan-integrations-formats.test.ts the command imports from a JSON-LD, an RDF/XML and a JSON Schema manifest, checks each mod; passed: suite/mizan-integrations-formats.test.ts a slice is imported as the same typed vocabulary from Turtle, JSON-LD and RDF/XML, a blank

FR-027checkpassing

The manifest's format MUST also name json-schema, whose slice is $defs names and which needs no namespace and no rdfImport; --check MUST compare the slice a JSON Schema module's header names to the manifest's.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-integrations-formats.test.ts: the command runs a json-schema manifest with no namespace, and --check names a slice that drifted from the module's header

Proved by: mizan/suite/mizan-integrations-formats.test.ts

Tests: passed: suite/mizan-integrations-formats.test.ts the command imports from a JSON-LD, an RDF/XML and a JSON Schema manifest, checks each mod

FR-028checkpartly run

Each of the three readers and the JSON Schema importer MUST be checked in a test against an independent tool: the graph of a JSON-LD or an RDF/XML source equal to the graph rdflib reads from the same text, and the code lists and field names of a JSON Schema import equal to what jsonschema accepts and an independent resolution of the schema gives; where Python and these tools are not installed that test is skipped and says so.

Enforced (check): .github: bun test ./tests/ — tests/commons-mizan-importers.test.ts: rdflib reads the JSON-LD and RDF/XML to the reader's graph and jsonschema accepts the lists the import writes; skipped where Python and these tools are not installed (CI installs them, pinned)

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

Tests: skipped: tests/commons-mizan-importers.test.ts the graph the JSON-LD reader gives equals the graph rdflib reads; passed: tests/commons-mizan-importers.test.ts the code lists and field names a JSON Schema import writes agree with jsonschema and with ; skipped: tests/commons-mizan-importers.test.ts the graph the RDF/XML reader gives equals the graph rdflib reads

FR-029reviewno test run

A reader of an XML-based format MUST be hand-written TypeScript where it reads the real files of its format to the graph an independent tool reads, and MUST otherwise be the best tool for the job recorded as a typed Exception (0017-two-languages FR-003 and FR-004). The decision for RDF/XML is: no Exception, because the reader of FR-024 read twelve W3C RDF/XML files (the RDF syntax namespace, RDF Schema, OWL, SKOS core, PROV-O in two files, the organization ontology, DCAT 2, SHACL, OWL-Time, SSN and WGS84 position, 33 to 1,719 triples each, 8,848 in all, with <!DOCTYPE> entities, rdf:ID, parseType Resource and Collection, xml:base and datatypes) to a graph isomorphic to rdflib's, with the same triple count in each; an RDF/XML source it reads differently, or a format such as XSD that needs more of XML, MUST be taken to a pinned reader as an Exception.

Enforced (review): 0017-two-languages FR-007 — Whether an XML reader needs a pinned tool is judged on evidence recorded in the requirement: twelve W3C RDF/XML files read to rdflib's graph by the hand-written reader; the test of FR-024 keeps its features checked

FR-030checkpassing

Where a specification cites a control of NIST SP 800-53, the control MUST be imported, never typed by hand: the OSCAL catalog of the standard's tagged release MUST be fetched from its versioned URL, held to a pinned SHA-256, and sliced to the controls the specifications of commons cite, so that a control identifier a specification names is a key of the generated controls module; the first such import MUST be the slice of Rev. 5.2.0 for IFCCM and IFQS (CM-2 to CM-10, SA-10, SI-7, IA-5).

Enforced (check): .github: cd commons/libraries && bun test suite/ — mizan-nist-import.test.ts: the committed module names the controls the specifications cite, with the titles of the pinned catalog, and the import's offline check passes

Proved by: libraries/suite/mizan-nist-import.test.ts

Tests: passed: suite/mizan-nist-import.test.ts the committed module holds the configuration management controls the specifications cite,

Out of scope

  • What is standard: 0018-standards-first.
  • The RDF kernel's writers: 0012-ontology.

Edge cases

  • An import that needs three terms of schema.org: only those, per FR-005.
  • A source whose hash differs from its record: refused, per FR-006.
  • A source with an OWL restriction: the term is written, and a finding names the restriction, per FR-007.
  • A source with an RDF list in a field: a finding, per FR-007.
  • A round trip that adds or loses a triple: the import fails, per FR-008.
  • A slice that names ac-2.1 and a control the catalog lacks: the missing control is named and nothing is written, per FR-015.
  • A source whose bytes changed under the same URL: refused as a pin mismatch, with the pinned and the actual hash, per FR-006 and FR-014.
  • --check with no network: compared to the header offline, per FR-014.
  • A term of ours whose basis is maps to a NIST term: an SSSOM row, per FR-010.
  • An exporter whose output no independent tool reads: not shipped, per FR-011.
  • A term that could be proposed to schema.org: a bundle is prepared and nothing is sent, per FR-012.
  • A JSON-LD file whose @context is a URL: the context is named as a finding and the terms it would define are not read, per FR-021.
  • A JSON Schema definition that is a plain { "type": "string" }: the import ends and names it, per FR-022.
  • A JSON Schema property that is an anyOf of two schemas: named as a loss, the field name is still in the union, per FR-023.
  • An RDF/XML property with rdf:parseType="Literal": named and not read, the rest of the document is, per FR-025.

Assumptions

  • Hand-written parsers cover Turtle, N-Triples, JSON, JSON-LD and RDF/XML (FR-029 records the evidence for RDF/XML); XSD may need an Exception for a reader, decided when it is needed.
  • The first sources are candidates until Phase 0 of issue #10 confirms their format, version and license: schema.org, DPV, PROV, OSCAL (NIST and FedRAMP), FHIR and US Core, NIEM, SPDX and CycloneDX.

Open questions

OQ-1open question

Which XML reader, if one is needed for XSD, becomes the first Exception (RDF/XML needed none, FR-029).

OQ-2open question

Whether imports are kept in this repository or in the importing harness, per standard.

Key entities

  • Integration - an import or an export, typed.
  • Registry - the lookup of integrations by format.
  • Slice - the named part of a standard that an import takes.
  • ImportRecord - the provenance of one import.

Success criteria

SC-001success criterion

A standard we use is imported, never hand-copied, and its generated module says where it came from.

SC-002success criterion

Each export is read by an independent tool in a test.

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

generate-ontology, Libraries, newer, publish-ontology, Mizan, integrations/host/import, integrations/mod, integrations/pure/export-dcat, integrations/pure/export-html, integrations/pure/export-owl, integrations/pure/export-rdfxml, integrations/pure/export, integrations/pure/import-json-schema, integrations/pure/import-oscal-catalog, integrations/pure/import-vocabulary, integrations/pure/provenance, integrations/pure/read-json-ld, integrations/pure/read-rdf-xml, integrations/pure/read-rdf, integrations/pure/registry, integrations/pure/types, Ontology, mizan/mizan, mizan/mod, The harness of Mizan, Libraries, Quality evidence, Mizan, the IF Spec Profile, The ontology in TypeScript, Standards first, Intellectual Frontiers Capabilities Configuration Management, Trust

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