Repository navigation
Building the ADIRO title-block TBox — module design and build plan #64
Replies: 1 comment
|
Proposal: also take alternative labels from drawing standards, not only from drawings This note says that The proposal. On a field kind of the Conditions:
Why it should not hurt extraction. A name that never appears on a drawing matches nothing. The two real risks are a name that collides with another field kind, which condition 2 excludes, and extra names in a prompt; if the second is a concern for the pipeline, the standard names could be left out of the prompted slice, as this note already suggests for First candidates (from #264): "Revision Index" on Does this exception look right, or should alternative labels stay harvested only? |
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Building the ADIRO title-block TBox — module design and build plan
Date: 2026-08-07 · Revised: 2026-08-11 · Status: initial
aec_titleblock.ttlwritten, 11 terms after PR #66 review (see §5); §1.1 still openWhat this is. The research note Title block standards research and alignment with ADIRO establishes which standards apply, which fields exist, and which of them are Data vs Object properties. This note is the build spec: where the terms live, what IRIs they get, in what order they are written, and what "done" means. It exists so the implementation decisions are reviewed before 40 properties are minted, not after.
1. Current state — what already exists [revised 2026-08-11]
src/aec_drawing_metadata.ttl(422 lines) declares:Titleblockas a labellable region class::Titleblock rdf:type owl:Class ; rdfs:subClassOf :MetadataContainer ; rdfs:label "Titleblock" ; :labellableRoot "true"^^xsd:boolean .That module is, in its original intent, a region ontology: it describes the detectable graphical regions of a sheet (
DrawingSheet,Layout,Titleblock,Legend,RevisionTable,Note) and their containment, and its:labellableRootannotations drive the CVAT annotation label tree.But it no longer stops there, and the first draft of this note was wrong to say so. It has since grown a sheet-level metadata layer that overlaps materially with what this module was going to mint.
1.1 The overlap, and how to reconcile it
aec_drawing_metadata:Person,:Project,:DrawingSheet,:DrawingRevisiontb:Person,tb:Project,tb:Sheet,tb:Revision(pass 1):StatusCode,:DrawingPackage:isAuthoredBy/:isCheckedBy/:isApprovedBy:DrawingRevision→:Persontb:createdBy/tb:checkedBy/tb:approvedByonTitleblock:drawingIdentifier,:drawingTitle,:hasScale,:sheetSize:DrawingSheet:revisionCode,:issueDate:DrawingRevision:hasStatusCode→:StatusCode:DrawingRevision:personName,:projectName,:projectNumber,:packageName,:statusLabelThat is roughly a third of the core-field list, and it collides head-on with the §10 acceptance criterion "no term duplicates one already in
aec_drawing_metadata" — as specified, passes 1 and 2 cannot both mint these terms and satisfy it.The subtler problem matters more. Those properties hang off
:DrawingSheetand:DrawingRevision, not off:Titleblock— the opposite of the modelling rule in §7 and of finding 2 in the standards research note, under which title-block content properties must have domainTitleblockbecause the title block asserts metadata and two sheets can assert conflicting values for one document. So the repo does not merely hold some clashing names; it holds a competing model of the same information, and this plan has to say what happens to it.aec_titleblockimportsaec_drawing_metadataand usesdm:Person,dm:Project,dm:DrawingSheet,dm:DrawingRevisionas ranges. Mint intb:only what does not exist:Organization,SourceFile,BoundingBox.DrawingRevision's existing shape rather than the fuller revision model — confirm that is sufficient (§11 q7).tb:assertion properties with domainTitleblockas a parallel layer, recording the correspondence explicitly:tb:checkedByis the asserted counterpart ofdm:isCheckedBy, the validated one. Promotion asserted → validated happens outside the TBox, as §7 already says.rdfs:comments, so nobody binds the wrong one.Proposed: A for classes + B for properties, with C recorded as explicitly rejected.Superseded for properties — see the resolution banner above. The classes half (A) still stands:Person,Project,DrawingSheet,DrawingRevisionare reused, not re-minted. This keepsaec_drawing_metadatauntouched (§2's whole point), avoids literal duplicates, and preserves the assert-vs-validated distinction that motivated the domain rule in the first place. It needs sign-off before pass 1: it is the decision that must not be made implicitly by whoever writes the skeleton, and option B knowingly leaves two vocabularies for the same concepts — which has to be a documented decision rather than an accident.2. Where the terms go: a new module, not an extension
Recommendation: a new module
aec_titleblock.ttl, importingaec_drawing_metadata. Not an extension of the existing file. Five reasons, all concrete::labellableRootinto CVAT labels and properties into attributes. Adding ~40 content properties and a dozen SKOS schemes to the region ontology floods an interface built for drawing bounding boxes. The two ontologies serve different annotation tasks and should be separately importable..ttlat a stable URL, and its own SemVer line, without a release of the title-block vocabulary dragging the region ontology's version with it.[revised 2026-08-11] There is no
aec_coremodule — the repo has four:aec_drawing_metadata,aec_common_symbols,aec_domain_common,aec_facade_domain. The real hierarchy for this work:The only edit to
aec_drawing_metadatais whatever:Titleblockneeds to be a usable domain — ideally none.Naming. Follow the existing convention (
aec_prefix, snake_case filename, module name matching the file). Prefix suggestion:tb:.3. IRIs — mint under
w3id.org/adiro[revised 2026-08-11]The first draft said to mint under
https://burohappoldmachinelearning.github.io/ADIRO/aec_titleblock#and let the deferred migration sweep it later. That sweep has already happened — every module now useshttps://w3id.org/adiro/, anddocs/contribute/versioning.mdrecords w3id as live and content-negotiating.So the intent of the original rule stands — never invent a bespoke base for one module — but the base to use is the current one:
Declare both
owl:versionIRIandowl:versionInfo, consistently with each other, starting at0.1.0— pre-1.0 signals honestly that the vocabulary is expected to break while the extraction experiment is running. CI checks the agreement, so an inconsistent pair fails the PR rather than shipping.4. Reuse before minting
[revised 2026-08-11 — ICDD is demoted, and de-blocked.] The first draft deferred all alignment axioms behind "obtain the normative
Container.rdf". Two things were wrong with that:https://standards.iso.org/iso/21597/-1/ed-1/en/Container.rdf, and itsct:local names are now recorded in §1.2 of the standards research note.ct:is container and file mechanics plus party provenance — it contains almost none of the ~40 title-block content fields, notitle/identifier/descriptionof its own, and nocheckedBy/approvedBy. Aligning to it was never what stood between this module and a usable vocabulary.So ICDD is not a blocker for any pass, and its alignment is conditional on a stated ICDD / openCDE deliverable requirement rather than something to do on principle. When a requirement appears it is roughly four class axioms, purely additive, a minor bump.
What reuse still means here:
ct:,dcterms:, IFC, LOIN) when a consumer needs them. Purely additive, minor version bump, touches nothing downstream.dici:hasContainerState→dici:InformationContainerState, withInitial/WorkInProgress/Shared/Published/Archivedas individuals). Suitability, discipline, type and the printed code strings are absent, as is anything title-block-specific — noRevisionclass, no scale, projection method, plan key or confidentiality. Against that, importing it would pull BFO/IAO into a suite governed by a blocking OWL 2 DL gate, and its repo has been dormant since 2022-06-30 at v0.5. So: mint our own, and borrow only the container-state pattern (§6). Any DiCon alignment is optional on-demand work, exactly like ICDD. Detail in §1.2 of the standards research note.Reuse directly and immediately where the vocabulary is free and stable:
dcterms:(title, identifier, creator, date),skos:(every controlled vocabulary),prov:(extraction provenance), lexvo URIs forLanguage— do not mint language individuals.[revised 2026-08-11] "Reuse before minting" now applies internally first: before minting any
tb:term, checkaec_drawing_metadata— per §1.1 it already holds several of them. Internal reuse is cheaper than external alignment and is checkable today, whereas ICDD alignment is blocked.5. Build order
Five passes, each independently reviewable and mergeable. Do not attempt all ~40 properties in one PR — a 40-property review gets rubber-stamped.
[revised 2026-08-11] Passes 1 and 2 are now conditional on the §1.1 decision, and their term lists shrink accordingly. A pass 0 is added: the §1.1 reconciliation must be agreed and recorded before any TTL is written, because getting it wrong means re-minting.
tb:extractionHint),owl:imports aec_drawing_metadata, plus only the supporting classes that do not already exist —Organization,SourceFile,BoundingBox; reusedm:Person,dm:Project,dm:DrawingSheet,dm:DrawingRevision.assertsMetadataForlinking:Titleblock→DocumentTitleblockand cross-reference thedm:term in both comments.Revisionper §5 of the standards research note — but see §11 q7 before minting a second revision classdm:StatusCode/dm:statusLabelalready exist — reconcile, do not shadowextractedFrom,hasBoundingBox,extractionConfidence,extractedByModel,hasValidationStatus,conflictsWithPass 5 is genuinely blocked, and passes 1–4 are genuinely not. Retrofitting provenance is expensive, and the test run creates the first real triples — so the decision needs making, but it must not hold up the vocabulary the run depends on.
With ICDD and DiCon both settled, passes 1–4 have no remaining external dependency — the only genuine block left is the RDF-star vs reification decision ahead of pass 5.
Passes 1–3 are what the extraction test plan actually needs to start. Anything beyond that is not on the critical path.
6. Enumerations: SKOS concept schemes, not
owl:oneOfThe existing module uses
owl:oneOffor:OrientationValue. Do not follow that pattern here, for a reason specific to these vocabularies: §3 of the standards research note says these fields are Object properties precisely because their values need mapping between code systems (a Uniclass code with an OmniClass equivalent) and hierarchy.owl:oneOfgives a closed set with no room forskos:broader,skos:notation,skos:altLabelorskos:exactMatch— it forecloses the capability that motivated the modelling choice. Useskos:ConceptScheme+skos:Conceptindividuals.[revised 2026-08-11] — why
owl:oneOfexists in the other module, which resolves the apparent inconsistency. The repo'sAGENTS.mdrecords that CVAT class labels come from the IRI local name, notrdfs:label, and thatrdfs:labelreaches CVAT only as the SELECT options ofowl:oneOfenumeration values. Soowl:oneOfis the pattern used there because those values must appear in a CVAT dropdown. This module is deliberately outside the CVAT label tree (§2 reason 1), so it has no such requirement. That strengthens the SKOS recommendation rather than weakening it, and explains the divergence without calling:OrientationValuewrong — the repo ends up with two conventions and a recorded reason for each, which was the point.owl:oneOfremains right for genuinely closed, tiny, non-mappable sets that need to reach CVAT; none of the schemes below are that.Schemes to build:
SuitabilityStatusContainerStateDocumentLifecycleStatusIfcDocumentStatusEnumConfidentialityClassificationDocumentTypeDisciplineProjectionMethod[revised 2026-08-13] Three options, not two — answering the PR #66 review question "why not classes, like
dm:LayoutContentType?" The review asked why the values are not listed the waydm:LayoutContentTypeliststhem (as OWL classes), or as a datatype list. There are three candidate patterns and they differ in what they
let you do later:
dm:LayoutContentTypedoes)Plan,Section, …dcommon:Disciplineas a hierarchy)owl:oneOfenumerationskos:broader, no code-to-code mapping, no notation. Adding a value is a schema changeskos:Conceptindividualsskos:notation(the code exactly as printed — what the extractor sees in the cell),prefLabel/altLabelper language,skos:broaderfor hierarchy, andskos:exactMatchfor mapping between code systemsskos:broadertraversal instead ofrdfs:subClassOfWhy SKOS here specifically. These fields were made object properties in the first place because their
values need mapping between code systems — a Uniclass code that also has an OmniClass equivalent, VS grades
alongside IFC's generic confidentiality values. Classes and
owl:oneOfboth foreclose that. SKOS also gives theone thing extraction most needs:
skos:notation, the code as printed, which is what the model actually readsout of a cell.
And why
dm:LayoutContentTypeis not a precedent to follow blindly. Its values reach the CVAT annotation UIas dropdown options, and
owl:oneOf/class labels are the only form CVAT picks up. This module is deliberatelyoutside the CVAT label tree (§2 reason 1), so it has no such requirement. The two conventions can coexist,
each with a recorded reason — which is the point.
Where a hierarchy really is wanted, reuse the existing class hierarchy instead of building a scheme. That is
what the review concluded for
Discipline:dcommon:Disciplinealready exists as classes, so a SKOS schemewould have duplicated it and lost the sub-discipline rollup. SKOS is for the code-carrying vocabularies, not
for everything.
[revised 2026-08-11] Independent corroboration for
ContainerState. DiCon models exactly these four states as named individuals of adici:InformationContainerStateclass, reached viadici:hasContainerState(§4). That is the same shape proposed here, arrived at independently from the same ISO 19650 clause — worth noting at review as evidence the individuals-not-enum reading is the normal one. Mint ADIRO's own concepts; if DiCon interop is ever wanted, two or threeskos:exactMatchaxioms cover it.Every concept gets
skos:notation(the code as printed on the drawing) andskos:prefLabel+skos:altLabelin en and de. The notation is what the extractor will actually see in a cell; the labels are what a caption might say.dm:StatusCode/dm:statusLabelalready exist and cover part of this ground informally — fold them into the reconciliation rather than shadowing them silently.7. Property template
Every property follows the same shape, which is also what gets sliced into the extraction prompt:
tb:checkedBy a owl:ObjectProperty ; rdfs:label "checked by"@en ; rdfs:domain dm:Titleblock ; rdfs:range dm:Person ; rdfs:comment "The person who checked the drawing, as asserted by this title block. ISO 7200:2004 §5.3.4 notes that checking specialists may be named in the title block but defines no dedicated field. Distinct from approvedBy. See dm:isCheckedBy for the validated, revision-level counterpart." ; skos:altLabel "checked"@en, "chk"@en, "chkd by"@en, "geprüft von"@de, "geprüft"@de, "gepr."@de ; tb:extractionHint "Usually initials or a short name, adjacent to 'drawn by' and 'approved by' in a row of role cells." .Rules that are easy to get wrong:
rdfs:labelper term, in English. This template previously showed aGerman
rdfs:labelalongside the English one. ROBOT'sreportraisesmultiple_labelsas an ERRORfor any term carrying more than one, and
AGENTS.mdalready puts alternate and short forms inskos:altLabel. Written the old way, the ~40 properties in this plan would have produced ~80 ROBOTerrors. German and abbreviated captions go in
skos:altLabel— which is where the extractor wants themanyway, so nothing is lost. Found by running the reasoning CI against the initial module.
Titleblock, neverDocument. The title block asserts metadata; two sheets can assert conflicting values for one document. Promotion to the Document happens after validation, not in the TBox.dm:. Under §1.1 option A, ranges reusedm:Person,dm:Project,dm:DrawingSheetrather thantb:twins. Only mint atb:class where none exists.dm:counterpart inrdfs:comment, in both directions where practical. This is what makes option B a decision rather than an accident, and the comment is a prompt token that earns its place — it is exactly the confusion an extractor would otherwise fall into.rdfs:domainis an inference axiom, not a constraint. Assertingtb:checkedByon any subject makes a reasoner infer that subject is aTitleblock— it will never flag an error. If a constraint is wanted, it belongs inshapes.ttl. Do not use domain/range as validation; that misunderstanding is the most common OWL trap and it will produce silent nonsense in a graph populated by an LLM. Since the reasoner became a blocking gate, a careless domain axiom can now also make the merged suite inconsistent and fail the PR outright.skos:altLabelis harvested, not invented. Populate it from the real caption inventory produced by annotation. A guessed altLabel set is a guess about German drawing offices, and it is the one component whose quality directly sets the extraction ceiling.skos:examplevalues in the prompted slice — they are an answer-leakage path. Keep them out of the module, or mark them so the profile generator strips them.hasLegalOwner/hasClient/hasOriginator,createdBy/checkedBy/approvedBy, the three status properties,title/supplementaryTitle. Elsewhere, keep them short; they are prompt tokens.8.
extraction_profile.ttlis generated, not writtenThe extraction experiment needs a small slice of this module in the prompt. Write the slicer as part of this work:
scripts/build_extraction_profile.py --properties <list> --out extraction_profile.ttl, strippingskos:exampleand any alignment axioms the model does not need, and recording the sourceowl:versionInfoand a token count.A hand-maintained profile drifts from the ontology within two weeks, and that drift silently corrupts the key-mapping metric — the exact failure already guarded against on the ground-truth side. Guard both sides.
[revised 2026-08-11] Under §1.1 option B the slicer has one more job: the profile must contain only the assertion-layer (
tb:) properties, never theirdm:counterparts. A profile that offers the model both vocabularies for one concept invites exactly the mis-binding that the property enum in the prompt schema exists to prevent — so make thetb:-only filter an explicit, tested behaviour of the script, not an incidental consequence of the property list passed in.The same applies to the ground-truth form: generate it from the module.
9. SHACL shapes
shapes.ttlships with the module — separate file, separate namespace, not mixed into the TBox. The three highest-value rules:revisionIndex/dateOfIssueon everyRevision(ISO 7200 §5.1.4 permits either alone — so neither may besh:minCount 1individually; this is ansh:or).Also add the cheap type-discipline shapes, which are what catch the failure mode of a syntactically perfect but semantically wrong binding:
sh:datatype xsd:datewhere dates are expected,sh:class tb:Organizationon organisation-valued properties,sh:inon SKOS-valued ones.10. Acceptance criteria [revised 2026-08-11]
uv run python scripts/validate_ontology.pypasses on the new module.uv run python scripts/generate_docs.pyproduces the module's pages without warnings, and the regenerateddocs/is committed in the same PR (never hand-edited).bash scripts/run_reasoning.shbefore pushing.reportraises no new issues; treat aduplicate_labelwarning as a design signal, not noise — because this module importsaec_drawing_metadata, a collision is early warning of exactly the §1.1 duplication problem.sampled sheets is deferred, not minted, to avoid a vocabulary full of properties nothing populates. This makes
the field-frequency survey a gating input rather than a nice-to-have — every remaining marginal term is a
claim that survey will confirm or refute. The survey need not be exhaustive: a project-level scan of which
concepts appear, plus drawings-per-project, gives a usable order of magnitude.
ISO 19650-2 for title-block search, and add ISO 21597-1 (ICDD) as the anchor for the document-to-document links
that cross-sheet linking needs. Treat IEC 82045 as a completeness check, not an implementation obligation.
Where an external ontology already models something, link out to it rather than importing it wholesale.
cannot be used and should not be merged — the PR feat(aec_drawing_metadata): title-block vocabulary, KeyPlan and layoutTitle (RES-89) #66 objection to
DocumentType. Land each scheme complete, inone pass.
owl:versionIRIandowl:versionInfoagree — now machine-checked, not a manual review item.aec_drawing_metadata, except the assertion-layer properties explicitly enumerated and justified in the §1.1 decision record. (The original criterion also namedaec_core, which does not exist.)dm:counterpart in its comment (§7).build_extraction_profile.pyruns, emits atb:-only profile, and records its token count.catalog-v001.xmlentry,generate_docs.pydependency order,mkdocs.ymlnav,changelogs/aec_titleblock.md,.display.json.11. Open questions for review
[revised 2026-08-19] Question 6 (placement) is now resolved — see below. Question 7 is next and outranks the rest of what remains. Questions 1, 3 and 5 are also settled/answered.
New module vs extending— SETTLED 2026-08-11, agreed by Ahmed Elnagar and Alessio Lombardi: the module stays separate, on ease of publishing and the volume of classes it will carry (§2 reasons 4–5).aec_drawing_metadataskos:ConceptSchemevsowl:oneOffor enumerations (§6). The CVAT mechanism in the revised §6 explains why the two conventions can coexist with a recorded reason; confirm that reasoning is accepted. Ifowl:oneOfis preferred for consistency anyway, the code-mapping capability has to be given up explicitly rather than by accident.Mint now underSettled — the repo already migrated togithub.io, or wait for w3id?w3id.org/adiro; mint there (§3).HoldAnswered by the repo — there is noPerson/Organizationhere, or promote them toaec_core?aec_coreto promote to, andPerson/Projectare already inaec_drawing_metadata. Reuse them; mint onlyOrganizationintb:, and revisit if a second consumer appears.§1.1 — how do we reconcile with the termsRESOLVED 2026-08-19 — Option 1: reuseaec_drawing_metadataalready has?dm:directly for all 10 overlapping content properties, notb:counterpart minted, no parallel assertion layer. Seedocs/modularization/titleblock-placement-option1-plan.md.dm:DrawingRevisionsufficient, or does the fuller revision model need a separatetb:Revision— and if so, how do the two relate? Two revision classes in one imported suite is a real cost; prefer extending the existing one if it can carry the history model.src/*.ttlglob trap (§9)?Related notes published here: ADIRO title-block properties — Data vs Object property design (the research this build spec implements) · Evaluating a predicted knowledge graph against a ground-truth knowledge graph · Ground-truth labelling: ontology-bound keys, or verbatim captions?
All reactions