Exported RDF uses terms absent from the published ontology — Ontology.py tables and topologicpy.ttl define different vocabularies

[PabloMarRod]

Summary

The vocabulary defined in src/topologicpy/Ontology.py (the internal OBJECT_PROPERTIES / DATA_PROPERTIES tables and the class hierarchy) and the published vocabulary in ontology/topologicpy.ttl have diverged. As a result, RDF graphs produced by the exporter reference ~29 properties that are not defined in the ontology they are supposed to conform to, so exported graphs do not validate against topologicpy.ttl.

Both files were introduced together in the same commit (b6b8f69, 2026-05-31), and the TTL declares dcterms:modified "2026-05-24", owl:versionInfo "0.1.0". Neither file has been edited independently since, so the two definitions appear to have been generated at different points and committed already out of sync.

How to reproduce

Parse the published TTL, collect the top: terms it defines, then collect the top: terms the exporter emits, and diff them. Every emitted term should be defined in the vocabulary; 29 are not.

Category 1: emitted term has a different name in the TTL (19)

The exporter emits these, but the TTL defines the right-hand form:

Ontology.py emits	topologicpy.ttl defines
top:hasVertices	top:hasVertex
top:hasEdges	top:hasEdge
top:hasFaces	top:hasFace
top:hasShells	top:hasShell
top:hasWires	top:hasWire
top:hasCells	top:hasCell
top:hasCellComplexes	top:hasCellComplex
top:hasInternalBoundaries	top:hasInternalBoundary
top:hasStartVertex	top:startsAt
top:hasEndVertex	top:endsAt
top:hasX / hasY / hasZ	top:x / y / z
top:hasArea	top:area
top:hasLength	top:length
top:hasVolume	top:volume
top:hasMantissa	top:mantissa
top:hasUnit	top:unit
top:updatedAt	top:modifiedAt

Category 2: emitted concept absent from the TTL entirely (10)

These are defined in the Ontology.py tables and emitted, but have no counterpart in the published vocabulary:

top:Point, top:hasDirection, top:interfaceOf, top:isPartOf, top:hasFreeVertices, top:hasFreeEdges, top:hasFreeWires,top:hasFreeFaces, top:hasFreeShells, top:hasFreeCells.

Two related bugs noticed alongside

1. Duplicate dict key. In OBJECT_PROPERTIES, "top:connectsTo" is defined twice (consecutive lines ~279–280); the second silently overwrites the first.
2. Ontology IRI stamp. The exporter emits top:TopologicPyOntology rdf:type owl:Ontology, i.e. a fresh entity in the top: namespace, rather than the canonical ontology IRI <http://w3id.org/topologicpy> that topologicpy.ttl declares.

Question before a PR

I'm happy to prepare a fix, but the direction depends on which artefact you consider canonical:

• (A) the published topologicpy.ttl — in which case I'd align the Ontology.py terms to the TTL names and add the 10 missing concepts to the vocabulary; or
• (B) the Ontology.py tables — in which case the TTL would be regenerated from them (a breaking change to the published v0.1.0 names, so presumably v0.2.0).

Either way I'd add a round-trip test asserting that every emitted term is defined in the ontology, so this can't drift again. There are a few smaller modelling points (e.g. owl:imports for BOT/Brick/PROV, dimensional disjointness) that I'll raise separately to keep this issue focused.

@wassimj Happy to send the PR once you've indicated A or B.

[wassimj]

@PabloMarRod Thank you! It is great that you took the time to inspect this and find the bugs. This is an initial effort as you correctly predicted. Before we move to a PR and make schema decisions, I would like to seek your advice on best practice:

1. A Topology such as a CellComplex has several: cells, shells, wires, faces, edges, vertices etc. Would the graph of this CellComplex have one edge for each cell in the "cells" list? In that case we would use "top:hasCell" and have several relationships, one for each cell. Same goes for all the other topologies. Or, is it more standard to have "top:hasCells" and the object is a "list" of cells? I am leaning to the first option, but your expertise here is valuable in terms of standard practice.

2. I am not sure why I have top:Point. This is not something topologicpy uses (We use top:Vertex). Can you shed some light on where this is used and if not used, we should dispose of it.

3. Have you tested the actual methods inside topologicpy and are they consistent? Do they record and emit the correct ontologies? Does information get lost anywhere in the process?

Thank you!

[PabloMarRod]

@wassimj let me see if i can clear those questions... i find it hard sometimes to provide ontological advice in written format without it being too technical.

1. Your first option is the correct best practice: a singular predicate repeated once per member. Something like:

   inst:cc top:hasCell inst:c1, inst:c2, inst:c3 .

Indeed, RDF properties are multi-valued by nature, so you express multiplicity by repeating the triple rather than pointing at a list. The list form (top:hasCells -> an rdf:List/Bag) is an anti-pattern here: it's awkward in SPARQL, it pushes the ontology outside OWL 2 DL so reasoners can't use it, and you lose the ability to type or describe each member. Singular naming also pairs naturally with the inverse properties you already have (top:hasCell / top:isCellOf). The one exception is order-bearing relationships (a Wire's vertices, a Path's nodes), where sequence matters. There you do need an explicit ordering (an rdf:List, or the indexed node approach your top:index already hints at), but only for those, not for the unordered cell/face/edge aggregations.

2. Regarding top:Point, it seems irrelevant in your semantic layer. It appears only in the class-hierarchy table (declared as a subclass of top:Vertex) and is never instantiated or emitted. Since topologicpy models points as Vertex, it's seems safe to remove.

3. Round-trip fidelity. I tested export -> re-import on a CellComplex adjacency graph (17 nodes, 16 edges) and there is information loss:

• All edges are lost (16 -> 0), with no error case. The exporter writes relationships as reified nodes with integer indices (top:src / top:dst), but the importer (GraphByRDFGraph) reconstructs edges from top:hasStartVertex / top:hasEndVertex, which the exporter never emits. The two encodings don't meet, so no edges come back and no warning is raised. (GraphTriples also contains a hasStartVertex/hasEndVertex branch, so both encodings exist in the code; only src/dst fires on export.)
• Vertex coordinates are not serialised, so re-import produces a synthetic layout rather than the original geometry. Fine if a graph is purely topological, but a conscious choice to make I guess.
• Reserved keys overwrite user data: a node dictionary with category="space" came back as category="node", because the exporter's reserved 'category' key clobbers the user's.

Node count and scalar user attributes (name, area) survive intact, so the node layer is mostly faithful; the relationship layer and geometry are not.

In summary, the export and import paths were written against different predicate vocabularies, which is the same root cause as the validation issue — so a single reconciliation pass (align exporter, importer, generator and the remap table to the published TTL, then a round-trip test asserting node/edge/attribute fidelity) would fix validation and round-tripping together. Happy to take that on once you confirm the published TTL is the intended source of truth.

[wassimj]

Dear @PabloMarRod,
Thank you for the detailed response. Here is my response:

1. Agreed regarding the first option: hasCell NOT hasCells. Ordered sub-topologies are very rare in topologicpy. Wires can be non-manifold, so order is not compulsory. If anything is ordered (manifold wire, topologicpy should/will add its index).
2. We can delete top:Point.
3. Round-trip fidelity: Now I understand why you are seeing conflicts in the ontology!! Graph.ByRDF is obsolete. Was written for a previous ttl effort. Please put that on hold as the whole Graph class is being deprecated in favour of a new, much more powerful graph class. More on that soon.
4. Vertex Coordinates: Same. The new graph class will emit that.
5. Reserved keys: This one is tricky. I encountered it myself with the "type" reserved keyword. I don't know what to do except warnings to users not to use a list of reserved keywords in dictionaries.

[wassimj]

Dear @PabloMarRod, Can you please check the new version of topologicpy (v0.9.56 or newer)? Ignore Graph.py. Instead focus on TGraph.py, KnowledgeGraph.py, and IFC.py. Please let me know if you still find any inconsistencies. Thanks.

[PabloMarRod]

Hi @wassimj,

I have re-ran everything against v0.9.57 across TGraph, KnowledgeGraph, and IFC.

Progress since the last round: all node coordinates now serialise (top:x/y/z), all edges use the defined top:startsAt/top:endsAt, KnowledgeGraph is a clean rdflib-backed layer that round-trips with no triple loss, and the IFC→ontology mapping tables are correct (classes and relationship predicates resolve to defined terms, nodes are typed by semantic class, ValidateBrickMappings runs). 👍

However, a few inconsistencies remain. I have paired each with a proposed fix.

1. Node URI collision

_OntologySafeLocalName returns "unnamed" for any node without a label, and the node URI is built from that local name with no uniqueness suffix. A CellComplex adjacency graph therefore exports to a single individual inst:unnamed, and every edge's startsAt/endsAt points to it — collapsing the topology into self-loops.

Fix: mint the node URI from a guaranteed-unique key already tracked (the uuid or index), e.g. inst:node_<uuid>, exactly as edges already do with edge_<…>. Keep _OntologySafeLocalName for the human label only, which moves to rdfs:label — never the URI.

2. Graph serialisation emits undefined predicates

Most are near-misses to terms that already exist:

• top:src / top:dst → rename to the existing top:srcId / top:dstId.
• top:relationship (the "Direct" label) → use rdfs:label, or type it via rdf:type subclasses of top:Relationship, rather than a bare literal.
• top:index → add as an xsd:integer datatype property (no equivalent exists; legitimate ordinal).
• top:directed / top:active → either add as xsd:boolean, or model direction structurally (directed = startsAt/endsAt; undirected = the already-defined symmetric top:connectedTo) and drop the booleans if they're runtime-only.
• top:uuid → pick one identity scheme: add top:uuid or reuse the existing nodeId/edgeId/graphId, not both.

3. IFC metadata under undefined predicates

IFC.TGraphByPath emits top:IFC_global_id, IFC_id, IFC_key, IFC_name, IFC_type — none defined.

Fix: align the emitter to the canonical ifc* terms — IFC_global_id → ifcGlobalId (exists); add ifcName and ifcType for IFC_name/IFC_type; IFC_id (STEP id) is file-local, so either add ifcStepId or drop it. I wasn't sure what IFC_key carries — happy to map it once you confirm.

4. Internal keys leak into the IFC export

Two kinds:

• dictionary_mode, import_mode, color are processing/display params. I recommend to filter them out (skip a reserved denylist, or prefix internal keys with _ and have the serialiser skip those).
• ontology_predicate, inverse_predicate, ifc_relationship look like they carry the predicate to use. They should be consumed to emit the correct edge predicate (and inverse), then dropped, not written verbatim.

5. Ontology-side convention triplication

The vocabulary now defines the same concept in two or three parallel conventions:

• area / hasArea, x / hasX
• ifcClass / ifc_class
• ontologyClass / ontology_class / ontologyURI / ontology_uri / uri
• createdAt, modifiedAt / updatedAt
• derived_from / source / generated_by / generatedByMethod

Fix: settle on one convention (I'd suggest lowerCamelCase, no has prefix for datatype properties, since those forms already exist), then for each duplicate mark owl:deprecated true with owl:equivalentProperty to the canonical term so existing data still resolves, and point the exporter at the canonical terms only.

6. Arbitrary dictionary keys pass through as top:<key>

A "name" key becomes top:name, etc. Minting user-supplied keys in the top: namespace is what pollutes it with undefined terms.

Fix: reserve top: for defined vocabulary; emit unmapped dictionary keys under a separate instance/data namespace, with an optional small map for well-known keys (name → rdfs:label, area → top:area).

Suggestion moving forward

I'd fix the URI minting (1) and reconcile emitted predicates against a single-convention vocabulary (2–5) together, then add a round-trip + validation test asserting that (a) every emitted top: term is defined in the ontology, and (b) a known graph survives export/re-import with node count, edges, adjacency, and attributes intact. Points 1–4 would all have been caught by that test.

Happy to prepare a PR along these lines. The decision that drives most of the other issues is which naming convention to standardise on (point 5). Let me know and I'll start there.