Build a working ontology from defence logistics data

The maintenance team changes its question: “WO-204 needs two filters and one replacement seal. Which requirement is blocked, and by which evidence?” The original model cannot express those two part-and-quantity pairs safely. This chapter implements the change, migrates the existing records, and tests the resulting graph.

You will create a PartRequirement class, preserve the original order identity, add three source files, and run a query that keeps each part's evidence and shortage separate. The complete downloadable lab includes the finished extension under extensions/multipart/; its implementation is multipart_lab.py. All steps below run locally with the Python environment prepared in Chapter 2.

The first model has one part and one requiredQuantity directly on a WorkOrder. Adding a second value to both properties would say “this order has PF-9 and SEAL-2, and quantities 2 and 1.” It would not say which quantity belongs to which part. A query could produce the wrong pairings. A comma-separated string such as PF-9:2,SEAL-2:1 would hide that structure inside text.

Give each requirement its own identity. WO-204-R1 owns the filter/count pair; WO-204-R2 owns the seal/count pair. Both belong to the same order. This is why a line item becomes a class: the relationship itself has facts that need to stay together. Later, a requirement could carry its own due date or approved substitute without overloading the WorkOrder.

A relational database can model the same structure with an order-requirement table. The useful ontology lesson is explicit meaning, stable identity, and relationships that several systems can share. Subtracting stock does not, by itself, justify adopting a graph database.

Open extensions/multipart/multipart_lab.py and find model(). It starts from the six-class baseline schema, changes its version to 2.0.0-multipart, and adds these terms. This Turtle fragment describes the same additions; the script generates the complete results/schema.ttl file.

The WorkOrder now needs one or more requirement links. Every PartRequirement needs exactly one order, one part, one positive integer requiredQuantity, and one unit equal to each, plus its organization and record ID. The ordinary part, requiredQuantity, and unit properties remain valid on requirement records.

The migration also forbids those three old properties directly on a WorkOrder. Without that check, old and new consumers could read two conflicting versions of the requirement. These are the actual added work-order constraints from model(); the existing asset, organization and ID constraints are retained. minCount and maxCount constrain the number of values in the data being validated.⁶⁰¹

The extension loads the already verified baseline graph into memory. It does not modify the baseline's CSVs or generated files. For each existing order, build() first creates a requirement whose stable ID is the order ID followed by -R1. It copies the original part, quantity and unit into that record, links the record to its order, and copies the original source-row lineage. Only then does it remove the three old properties from the in-memory WorkOrder. For order IDs longer than 77 characters, migrated_line_id() uses a deterministic shortened ID with a hash suffix to stay within the 80-character identifier limit; the original order identity is unchanged.

The line() helper performs the guarded creation. It rejects unknown or cross-organization references, duplicate requirement IDs, unsupported units, and a repeated part on the same order. The last rule prevents two lines from independently counting the same available stock. Supporting split lines would require an explicit allocation policy, not simply removing that check.

For the supplied dataset, results/migration.json records two migrations: ORG-TRAIN's WO-204 becomes WO-204-R1, and ORG-OTHER's WO-888 becomes WO-888-R1. Their original order, asset and part identifiers are preserved. The additional requirement comes next; it is not invented while migrating old records.

Provenance stays attached to the source records that support each migrated line, and an additional activity identifies the migration. This uses PROV's derivation and activity relationships to describe lineage.⁶⁰² It does not turn the migration into an authenticated audit service. Compare the baseline file hashes before and after if you want to verify that its files were preserved; the test suite makes that comparison automatically.

The extension's three small CSV files are already included. Their paths are relative to the lab directory. Keep the exact headers when creating a fresh copy. First, extensions/multipart/fixtures/parts.csv defines the new part type:

Next, extensions/multipart/fixtures/inventory.csv declares three fictional physical seal identities. The observation uses the same time as the baseline's stock records so the existing freshness policy applies consistently.

Finally, extensions/multipart/fixtures/requirements.csv says that the work order needs one of that part type:

Three seals are an explicit exercise input, not a measured operational count. This closed fixture declares zero reservations and zero quarantined seals; existing filter allocations remain unchanged. A real importer would need a completeness contract for its allocation feed before interpreting an absent row as zero. The extension also checks that the three seal unit IDs are unique and match on_hand.

From the directory containing ontology_lab.py, run these commands. If you have just extracted the archive, the first two rebuild and verify the baseline before migrating it. Each failure stops the sequence so an invalid build is not mistaken for an expected result.

On Linux or macOS, use .venv/bin/python in place of the Windows interpreter path. The recorded execution used Python 3.12.10 on Windows. The extension uses the baseline's pinned dependencies; it installs nothing and calls no remote service during the exercise.

Inspect extensions/multipart/results/schema.ttl, shapes.ttl, and instances.ttl. The supplied inputs produced 168 instance triples, 100 provenance triples, and three PartRequirement records across both organizations. The validation command returned conforms: true. Find WO-204 and confirm it has two requirement links and no direct part or quantity property. This checks the model change, rather than only the program's exit code.

The fixed query is extensions/multipart/requirements_inventory.rq. It follows WorkOrder → PartRequirement → PartType → StockSnapshot, binds the selected organization on every business join, and aggregates existing allocations per stock snapshot. Its key change is that the requirement is mandatory but its stock match is OPTIONAL. SPARQL's optional pattern permits a result to retain a requirement when matching stock information is absent.⁶⁰³

That matters operationally. If a seal snapshot is missing, the requirement must remain visible as unresolved; dropping the entire row could make the order look complete. The Python query handler requires exactly one in-scope stock snapshot per requirement. Missing or multiple snapshots produce a null availability and an explicit issue. It applies the baseline's two-hour freshness rule to stock, existing allocations and inspection evidence.

The actual result in extensions/multipart/results/explanation.json contains these values:

For PF-9, available = 6 on hand − 3 reserved − 2 quarantined = 1. For SEAL-2, available = 3 on hand − 0 reserved − 0 quarantined = 3. All quantities use each.

The whole order's status is shortage_needs_human_review. A surplus of seals cannot cancel a shortage of filters, so there is no summed cross-part shortage field. Each line carries its own source locators, including the original filter rows or the added seal CSV rows. The inspection remains pending, and maintenanceReleaseAllowed remains false.

Use a disposable copy of the lab. In the extension's requirements.csv, change only required_quantity from 1 to 4. The changed data row should read:

Run the query before rebuilding: it must refuse the changed source with an explicit rebuild-required error. Then rerun the extension's build, validate and query commands. PF-9 remains needed 2, available 1, shortage 1. SEAL-2 becomes needed 4, available 3, shortage 1. Restore the original quantity and rebuild before comparing with the shipped output.

This exact exercise is implemented in test_increased_second_requirement_has_its_own_shortage. It demonstrates a useful property of the new model: changing one line's quantity leaves the other line's meaning and arithmetic intact. No code change is needed for this data change because the ontology already represents one-to-many requirements.

The extension suite runs 20 tests against temporary fixture copies. Its reports are extensions/multipart/results/test-summary.json and test-results.txt; the baseline has its separate 24-test suite. These are executable acceptance checks for the local implementation, not claims of load testing or operational accreditation.

What you created: a new ontology class, explicit one-to-many relationships, a versioned migration, additional source mappings, revised constraints, a per-requirement query, and tests that check both preserved behaviour and new failure cases. What to check: both requirement identities exist, source locators resolve, the old WorkOrder fields are absent, and the observed query values match the table.

The remaining deployment work is concrete: authenticated identity, source-feed completeness, authorized reads, live revision/freshness checks, depot selection, allocation across competing orders, and durable approval/action handling. The local --org flag implements none of those services. Keep the reproducible graph and tests as the acceptance baseline when adding them.