Skip to main content

Specification: Competency Questions and the ORSD

📍 Where we are: Part I · Specification — the first move in the lifecycle. Before a single class is drawn, we write down what the finished ontology must be able to answer. This chapter is the requirements specification the rest of the book is built and judged against.

A common way to start an ontology is to open an editor and begin naming classes. It is the wrong way, and it is worth saying why on the first page. An ontology is not a description of the world — the world is infinite, and you could model a cell down to its atoms or up to the org chart and never stop. An ontology is an instrument built for a purpose, and the purpose is to answer questions. So the discipline that has held up across every serious ontology-engineering methodology since the mid-1990s is the same: start from the questions, write them down, and let every later modeling choice be judged by whether it serves one [1].

The simple version

You don't build a house by buying bricks. You start with a brief: how many bedrooms, who lives here, what must it never do (leak, fall down). Then the brief becomes a blueprint, and at the end an inspector checks the finished house against the brief — room by room — before anyone moves in. A competency question is one line of that brief for an ontology ("can it tell me which batches share this cell bank?"), the ORSD is the whole brief, and this book's validate.py is the inspector: it runs every line of the brief against the finished model and fails the build if even one is unmet. Requirements first, then the model, then the inspection — never bricks first.

A left-to-right flow of the seven ontology-engineering lifecycle phases — Specify, Reuse, Conceptualize, Formalize, Implement, Validate, Maintain — each a rounded box with a bioprocess example beneath it (competency questions; BFO, IOF and OBO; classes and relations; OWL axioms; instances and ETL; SPARQL and SHACL; FAIR and versioning); a violet return loop runs from Validate back to Conceptualize, the SAMOD test-first iteration in which all 23 competency questions stay green; and three labelled bands show which methodology governs which phases — NeOn over specification through formalization, SAMOD over conceptualization through validation, and LOT over implementation through maintenance. The lifecycle this book follows: NeOn shapes the early phases and the ORSD, SAMOD drives the test-first loop in the middle, and LOT governs publication — with the running antibody campaign carried through every phase. Original diagram by the authors, created with AI assistance.

Three methodologies, one backbone​

This book does not invent a process. It follows the three ontology-engineering methodologies the field actually uses, and each governs a different stretch of the lifecycle the rest of the book walks:

  • NeOn gives the overall shape and the requirements artifact. The NeOn Methodology frames ontology building as a set of flexible scenarios — specification, reuse of existing ontologies and resources, conceptualization, formalization — rather than one rigid waterfall, and it is where the Ontology Requirements Specification Document (ORSD) comes from [2]. Part I (this part) and Part II (Reuse) are NeOn's.
  • SAMOD — the Simplified Agile Methodology for Ontology Development — gives the rhythm of every modeling chapter: a small, test-first iteration over a "modelet" — write the competency question, model the slice, test it against the data, refactor — repeated until the model is whole [3]. Parts III–VI run on SAMOD's loop.
  • LOT — the Linked Open Terms method — gives the back end: publication, versioning, reuse-first authoring, and FAIR release of the finished vocabulary [4]. Part VII is LOT's.

All three share the conviction this chapter opens with, traceable to Grüninger and Fox's founding work and codified for beginners in Ontology Development 101: an ontology's requirements are written as competency questions, and the model is validated by answering them [1][5].

The ORSD: a requirements brief for the model​

The ORSD is a short document, agreed before modeling, that fixes what the ontology is for. It has seven parts. Here is ours, for the CHO monoclonal-antibody process this book models end to end.

1. Purpose​

Turn one biologic-manufacturing campaign — from the discovery target to the cold-chain vial — into a single, machine-actionable knowledge graph, so that lineage, impact, quality-by-design, and release questions are answerable by query instead of by spreadsheet archaeology.

2. Scope​

In scope: the discovery-to-distribution path of one platform CHO mAb — genealogy (derivedFrom), critical process parameters and quality attributes and the links between them, the release specification and its gate, viral-clearance summation, serialization and containment, regulatory substance identity, and the provenance of reconciled source records.

Out of scope (named, not forgotten): clinical and patient data; financials and scheduling; real-time process control (the graph documents setpoints, it does not actuate them); a multi-product portfolio; and cross-organization federation beyond the factory wall — which the verdict treats as a genuine limit, not an omission.

3. Intended end-uses​

Lineage traceback; recall-impact scoping; CPP→CQA root-cause investigation; release verification; viral-clearance review; packaging track-and-trace; FAIR cataloging; and grounding for retrieval-augmented AI.

4. Intended users​

QA/QC reviewers, manufacturing-science (MSAT) investigators, regulatory-submission authors, data engineers and ontologists, and the platform/knowledge-graph vendors surveyed in Part VIII.

5. Functional requirements — the competency-question catalog​

The functional requirements are the competency questions. There are 23, grouped by the question they answer. Each carries a stable identifier (CQ-01 … CQ-23) used throughout the book, and — this is the point of the whole chapter — each is executable: it maps to a SPARQL query, a SHACL gate, or a reasoner check, and validate.py runs it as a pass/fail test (the next chapter shows the live result).

GroupCQThe question the model must answer
LineageCQ-01Given any downstream material, which materials does it derive from, to any depth?
CQ-03What is the originating bioreactor batch of a drug-substance lot, and its release monomer value?
ImpactCQ-02Given a working cell bank, which materials across the whole campaign descend from it?
CQ-04When a drug-product lot fails, which other products share its lineage (siblings via the cell bank)?
TrajectoryCQ-05What is the in-process HMW-aggregate value at each purification step (where did quality change)?
QbDCQ-06Which process parameters affect a given critical quality attribute?
CQ-07From a CPP, through its affectsQuality link and the run that realized it, to the released DS lot — does the chain resolve?
ReleaseCQ-08Does a released substance lot carry exactly one in-spec value for every required CQA?
CQ-09Is a released lot attributably signed, with a status from the controlled set?
CQ-10Do the finished product lots meet finish-specific criteria (sterile, appearance, fill volume)?
CQ-11Are out-of-spec lots flagged on exactly the failing path and nowhere else?
ViralCQ-12What is each orthogonal clearance step's validated LRV, and the summed total clearance?
PackagingCQ-13What serialized units are contained, transitively, within a given package?
CQ-14Is containment kept distinct from genealogy?
ProvenanceCQ-15Do two source-system records reconcile to one curated decision without an owl:sameAs over-merge?
CQ-16Does the ISO IDMP regulatory identity attach to the same node the release gate validated?
CharacterizationCQ-17Is the working cell bank fully characterized, so it conforms to the cell-bank gate?
CQ-18Is the working cell bank within its validated passage limit?
UnitsCQ-19Does every stored quantity carry a unit — no bare numbers?
CQ-20What host organism, by stable NCBI Taxon IRI, does the line express its product in?
StructuralCQ-21Which vessel did a cell-culture run occur in (equipment separated from the batch material)?
CQ-22Are the long-range transitive derivedFrom edges inferred, and is equipment inferred a BFO material entity?
CQ-23Do the disjointness guards catch planted conflations (a Batch typed as a process, or as a bioreactor)?

6. Non-functional requirements​

The qualities the model must have regardless of any single question: grounded (every class sits under BFO); reuse-first (align to public ontologies, mint only what is genuinely local); offline-validatable (validate.py needs no network); decidable (the model stays in the OWL 2 profile — the transitivity constraint on derivedFrom is honored, not faked); truthful (every snippet in the book is a real excerpt of the loadable dataset); bilingual (published EN/KO); and FAIR on publication.

7. Pre-glossary​

The handful of terms fixed before modeling, so two authors do not coin two words for one thing: Material, Equipment, Quality, Process, Information Artifact, Process Parameter; the relations derivedFrom, affectsQuality, occursIn, contains; and the domain terms CQA, CPP, cell-bank tier (RCB/MCB/WCB), LRV, release status.

Requirements that are tests: the executable ORSD​

Writing competency questions in prose is the normal practice. This book goes one step further and makes them a machine-readable, runnable artifact — because a requirement you cannot test is a requirement you cannot trust. The catalog above is mirrored byte-for-byte in examples/platform/ontology/cq-catalog.json, where each competency question names the artifact that answers it and the result it must produce:

{
  "id": "CQ-04",
  "group": "impact",
  "question": "When a drug-product lot fails, which other drug products share its lineage (siblings via the shared cell bank)?",
  "query": "CQ-04.rq",
  "graph": "raw",
  "check": { "type": "equals", "var": "affected", "values": ["DP-001", "DP-002"] }
}

Three kinds of artifact answer the 23 questions, and the split is itself a lesson in what each tool is for:

  • A SPARQL query answers most of them (17 files, queries/CQ-01.rq … queries/CQ-21.rq) — a SELECT whose row count, result set, matched row, or summed column is checked, or an ASK whose boolean is checked.
  • A SHACL gate answers the closed-world ones (CQ-08, CQ-10, CQ-11, CQ-17) — completeness and in-spec questions a query cannot pose, because "is anything missing?" is not a question about the triples that exist.
  • A reasoner check answers the structural ones (CQ-22) — that the OWL-RL closure actually inferred the long-range lineage and the equipment typing.

validate.py reads the catalog, runs every entry, prints a pass/fail line per competency question, and exits non-zero if even one fails. The requirements document and the test suite are now the same file. When a later chapter adds a class or an edge, it does not get to claim success until the relevant CQ-XX still passes — which is exactly the SAMOD test-first loop, enforced by a script rather than by good intentions. The next chapter introduces the dataset those tests run against and shows the full table, green.

The unsolved part: a brief is a judgment, not a proof​

The ORSD disciplines the model, but it cannot certify that the right questions were chosen. A competency question catalog is a claim about what matters, made by people, before the hard cases are known — and a model that answers all 23 of its questions can still be useless for the 24th that no one thought to write down. Scope is the perennial failure mode: every investigator who hits a wall wants "just one more" entity, and an ORSD that grows without discipline becomes the boundaryless model it was meant to prevent. So the ORSD is a living document under the same change control as the ontology itself: new competency questions are proposed, justified, and either admitted with their own test or refused with a reason. The executable catalog makes the refusals honest — a question not in cq-catalog.json is a question the model does not promise to answer, and says so out loud.

Why it matters​

Starting from requirements is what keeps an ontology finite, testable, and trusted. Without the ORSD, "is the model done?" has no answer and "is the model correct?" has no test; with it, both reduce to running validate.py and reading 23 lines. Every later chapter in this book earns its classes and axioms by pointing at the competency question they serve — and if it cannot, the content does not belong in the model. That is the difference between an ontology that is engineered and a vocabulary that merely accreted.

In the real world​

The competency-question discipline is not academic folklore; it is the spine of the methodologies industry actually adopts. NeOn's ORSD template is used across European ontology projects and taught as the standard requirements artifact [2]; SAMOD's test-first loop mirrors how agile software teams already work, which is why it transfers cleanly to engineering organizations [3]; and LOT was built explicitly for industrial ontology development and is used in standards bodies and large companies to publish reusable vocabularies [4]. What is still rare — and what this book argues for — is making the competency questions executable, so the requirements and the regression suite never drift apart.

Key terms​

  • Competency question (CQ) — a query the finished ontology must be able to answer, written before modeling; the unit of requirement and, here, also the unit of test.
  • ORSD (Ontology Requirements Specification Document) — the agreed brief fixing the ontology's purpose, scope, users, uses, functional requirements (the CQ catalog), non-functional requirements, and pre-glossary.
  • NeOn methodology — a scenario-based ontology-engineering method; the source of the ORSD and of the reuse process Part II follows.
  • SAMOD — the Simplified Agile Methodology for Ontology Development; the test-first "modelet" loop each modeling chapter runs.
  • LOT (Linked Open Terms) — an industry-oriented method for requirements → implementation → publication → maintenance of reusable vocabularies.
  • Executable competency question — a CQ bound in cq-catalog.json to a SPARQL query, SHACL gate, or reasoner check, run as a pass/fail test by validate.py.

Where this leads​

The brief is written and made runnable. The next chapter, The Running Example and the Proof Harness, introduces the single monoclonal-antibody campaign every later chapter models, the dataset files that hold it, and the harness that turns this catalog of 23 competency questions into a table of 23 passing tests — the green baseline the whole book is built to keep.