0013 — Language bindings wrap the facade, one crate per target
- Status: Accepted
- Date: 2026-09-23
- Deciders: Friedrich Schrödter
- Supersedes: —
Context
The IFC crates reach only Rust consumers (#34). JavaScript, Python and native hosts need the same model — parse a file, read and edit entities, write it back — without adopting Rust types or Rust's unstable ABI. The three targets differ in calling convention and ownership, but not in what they expose.
Axiolid already ships a versioned C ABI (its ADR 0040). IFC bindings should feel the same to a host that loads both.
Decision
We will expose the IFC layer to other languages through one binding crate per target, each depending only on openbim-ifc, never on an ifc-* crate directly.
openbim-ifc-wasm(browser and Node, viawasm-bindgen),openbim-ifc-capi(C ABI) andopenbim-ifc-py(Python, viapyo3).- Amended 2026-09-23: host-independent binding code -- the model operations, the tagged
Valueencoding andBindingError-- lives once, inopenbim-ifc-binding-core, which depends on the facade and on no host toolkit. Each host crate depends on the core, not on the facade, so the three stay behaviourally identical: a value refused in one is refused in all, with the same errorcode. - A binding adds calling-convention glue only: no IFC semantics, no validation, no domain logic. If a binding needs behaviour the facade lacks, the behaviour goes into the facade first.
- The surface is the record model —
Model,Entity,Value, the STEP codec — not the domain crates. Domain projections are a later, opt-in layer. Valuecrosses the boundary as a lossless tagged encoding (a JS object per variant), not as native numbers and strings. IFC distinguishes$from*,.U.from.F., integer from real, and typed wrappers such asIFCLENGTHMEASURE(2.5)from their payload. Folding any of these into a host-native value would make a round trip silently lossy.- Each host carries that encoding in its own idiom: JS objects with
BigIntintegers (JS numbers lose precision above 2^53), frozen Python dataclasses, and a flat C node array with a string buffer (no recursive structs, so no Rust allocation crosses the C ABI). - Every binding has an executable round-trip smoke test in its host language that parses a file, reads an entity, edits one, and writes the file back.
- Amended 2026-10-03: beyond the record model, the bindings carry the facade's non-domain surface (#244): lenient STEP reads (
ParseOptions, their recoveries reported as diagnostics), the whole STEPHeader, read and replaced, schema validation as structured findings, the ifcXML codec in its native and XSD layouts, andunreachable_products. Each is bound once inopenbim-ifc-binding-coreand carried by all three hosts with the same records and error codes (new:unsupported-profile,feature-disabled). The capabilities that add to a browser build --ifcxml,validate,unreachable-- are default features of the core and the WASM crate, so a size-sensitive build leaves them out as it leaves out IFC releases (#112); a left-out capability keeps its methods and refuses withfeature-disabled, so every build has one surface. Checked multi-edit transactions (Transaction/Applied/Conflict) are deferred until a host asks for them. Domain views (#123) are the next layer, each an opt-in feature of the same kind. - Amended 2026-10-03 (#123, read side): the bindings carry the facade's domain views as owned snapshots. A view borrows
&Modeland cannot cross a boundary, soopenbim-ifc-binding-corebuilds each answer into plain records keyed by entity id, with theGlobalIdwhere the entity has one, and every host converts them with one generic function: a record is a named, ordered list of fields (a JS object, a frozen Python dataclass, a C tapeLIST). Bound read-only, each behind its own feature: property sets and quantities with type inheritance (exact, release-bound) and unit resolution, the spatial tree, classification, materials, systems, cost, and georeferencing (a new facade join ofgeorefandproperties, since the project length unit scales every operation). IFC values in them keep the tagged encoding, typed with their declared type; resolved parameters (thicknesses, map offsets) are host numbers. A release a view does not read is refused withunsupported-schema; new codesinvalid-model,missing-reference,budget-exceeded,unsupportedandwrong-entity-typekeep the domain crates' refusals distinct. All seven are default features of the core and the npm package, which carries every capability; writing property sets is the second half of #123. - Amended 2026-10-03 (#123, write side): the bindings write property sets as one checked edit, the first write the domain layer carries. The facade grows it first (
ifc::apply_property_edits): a batch of edits, each addressed by object, set name and property name as the read side reports them, is planned against the model, staged on oneTransactionand committed, or refused with nothing written. The value is the read side's taggedvalue. A value an occurrence inherits is overridden on the occurrence, never changed on the type's shared set; a set or property entity shared with other objects is copied before it changes. Values are checked against the declared release and, for aPset_/Qto_set, the release's PSD/QTO catalog (ADR 0017); new sets take the object's owner history and a name-basedGlobalId, since no randomness builds for every target. Hosts call itsetProperties/set_properties/openbim_ifc_v0_1_model_set_propertieswith one-edit forms beside it; the C batch is a value tape the core reads, so the three cannot read an edit differently. New codestemplate-violation(C 25) andmissing-property(26). The writer (properties-write) and the catalog (property-catalog, 3.7 MB of a browser build) are features of their own, default in every host; without the catalog a write to aPset_/Qto_set refuses withfeature-disabled. - Amended 2026-10-03 (#318, runtime catalog): the npm package no longer embeds the PSD/QTO catalog. Its module is built with
property-catalog-runtime; the package ships one pinned snapshot file per edition (catalog/<edition>.bin), andawait IfcModel.loadCatalog(release?)reads the one a release needs (Node from the package directory, a browser or bundle relative to the module, or bytes or a base URL the caller passes), checks it against its SHA-256 and keeps it for the module instance. Until its release is loaded, a write to aPset_/Qto_set refuses with the new codecatalog-not-loaded(C 27), never unchecked; removals and other sets need no catalog. Once loaded, the writer checks exactly as with the embedded catalog. The C and Python bindings keepproperty-catalog(embedded), so their behaviour and codes are unchanged; the core'scatalogmodule is the same surface in both builds. - Amended 2026-10-03 (#326, attributes by name): the bindings read and write an entity's attributes by name as well as by position. The facade grows it first (
ifc::attribute_slots,attribute_by_name,set_attribute_by_name): a name resolves to its slot in the release the header declares, never another, soIfcTask.Statusis slot 6 of an IFC2X3 file and slot 7 of an IFC4 one. The slots are the explicit attributes in Part 21 order, inherited first;INVERSEattributes hold none. Names match ASCII case-insensitively, as EXPRESS identifiers do, and come back in the schema's spelling. An inherited attribute a subtype redeclares as derived is listedderived, reads as stored (*) and refuses a write. Hosts call itattributeNames/attributeByName/setAttributeByName,attribute_names/attribute_by_name/set_attribute_by_name, andopenbim_ifc_v0_1_entity_attribute_names/_entity_attribute_by_name/_entity_set_attribute_by_name, beside the positional calls, which stay raw slot access. An entity type the declared release lacks isunsupported-schema; new codesunknown-attribute(C 28) andderived-attribute(29). A Pythonic object layer (wall.Name, #332) builds on these calls. Amended 2026-10-14 (#462): a read resolves anINVERSEname through the reverse index with the declared release'sFORclause (wall.IsDefinedBy), and a write to one is refused with the new codeinverse-attribute(C 35). - Amended 2026-10-04 (#327, .NET): .NET hosts (Revit, Navisworks, Tekla, Dynamo) get the
OpenBim.IfcNuGet package: C# P/Invoke over the versioned C ABI (openbim_ifc_v0_1_*) and nothing else, the one binding that reaches the core through another binding's boundary. The row of the alternatives table against thin layers over the C ABI was about hosts with a safe Rust binding generator; .NET has none that covers .NET Framework, and the C ABI already holds the conventions a host needs, so a second Rust host crate would add a toolchain and no semantics. The C# adds calling-convention glue only; a capability the C ABI lacks goes into the C ABI first, for every host. The package targetsnetstandard2.0(.NET Framework 4.6.2 and later) andnet8.0and carries the C ABI's shared library per runtime identifier (win-x64,win-arm64,linux-x64,linux-arm64,osx-x64,osx-arm64), taken from the C ABI's release archives rather than built twice; build targets copy the Windows libraries into a .NET Framework project, and the assembly loads them from next to itself. The model is anIDisposableover aSafeHandle;Valueis a closed record hierarchy with value equality;IfcExceptioncarries the sharedCodeand the C status; domain records are positional C# records decoded from the tape by one generic function, as the core intends; attributes by name (#326) areAttributeNames,AttributeByNameandSetAttributeByName. Two names differ from the other hosts: the core'sSystemrecord isIfcSystemandSystemsisSystemsView, since C# forbids or penalises the originals. The package lives in a thin crate,openbim-ifc-dotnet, with no Rust dependency (an architecture test pins that): it gives the package a version, a changelog, a release tag and a reference page through the existing tooling, and its tests hold the C# declarations to the C header and the C# records to the core's, field by field, in the gate without a .NET SDK. The package's own suite runs against the packed.nupkgfrom a fresh project, on every runtime before a release publishes it, through NuGet trusted publishing. - Amended 2026-10-04 (#332, Pythonic access): the Python package adds a pure-Python layer over its calls, in the package's Python sources and with no native surface:
Entityviews (model[id],by_type,wall.Namethroughattribute_by_name/set_attribute_by_name), property sets as read-only mappings overproperty_sets, and an optional pandas export. Its reads fold values into plain Python ones, the mapping the alternatives table rejects as the boundary encoding; it stays a convenience above that boundary, documented value by value as lossy where it is (*and.U.readNone, enumsstr, typed wrappers their payload), and the exact tagged value is one call away (raw). Writes still take tagged values: a barestr,int,floatorboolis refused rather than guessed. Subtype tests and type filters useids_of_type_including_subtypes, so the layer holds no schema knowledge of its own. - Amended 2026-10-04 (#330, entity creation): the bindings create entities, the first checked multi-edit transaction over arbitrary entities they carry. The facade grows it first (
ifc::apply_authoring, featureauthoring): a batch of operations runs in order against the model as the ones before it leave it and is committed as oneTransaction, or refused with nothing written. Every record is built by attribute name throughifc-author'sEntityBuilderagainst the release the header declares, then its references are resolved to an accepted type and its aggregates held to their declared bounds. The builders are facade compositions over that one checked create (project, spatial element aggregated under its parent, product placed, contained and typed, type object and assignment, containment, aggregation, local placement, an owner history throughifc-author's writers), and removal takes an entity out of every relationship;ifc-spatial's writers lay out IFC4 unless given an owner history, so they were not the base. An operation names an earlier one's entity by a handle, an id in a reserved range (2^62 plus its position), so references cross every host as plain ids andREFvalues with no new value kind. Each host converts its operation objects field by field, guided by the core'sOPStable, into one tape form the core reads (the C batch element), as with the property edit's tape. A newIfcRootgets a name-basedGlobalIdover a per-batch seed: the operating system's on native targets,Math.randomin the browser, where the module has none;OwnerHistoryis never invented. Hosts call itauthor/Author/openbim_ifc_v0_1_model_author, withcreateEntityandremoveWithRelationships(in each host's spelling) as one-operation forms. New codesmissing-attribute(C 30) andstill-referenced(31); a second containment, decomposition, typing orIfcProjectisinvalid-model. - Amended 2026-10-08 (#328, geometry): the bindings carry each product's world placement and selected Body by default and its mesh on request, refused per product with typed records; ADR 0021 records the decision and why the serialised neutral representation waits.
- Amended 2026-10-26 (#538, EXPRESS rules): each host gains a separate method that validates with the EXPRESS rules of the declared release from
.exptext the caller supplies (validate_express,validateExpress,ValidateExpress,openbim_ifc_v0_1_model_validate_express), parsed on every call withExpressRules::parseagainst the model's own tables. The text is never bundled: the schemas are CC BY-ND. The existingvalidatesignatures are unchanged -- an optional parameter would break the .NET binary and the frozenv0_1C symbol -- and there is no handle object and no hidden cache. New codesexpress-mismatch(C 36), for text that declares another schema or disagrees with the tables, andinvalid-express(C 37), for text that does not parse or names nothing in scope. Reports carry anindeterminatecount (rules that evaluated to UNKNOWN); the C binding addsOpenbimIfcExpressValidationSummaryfor it, since thev0_1summary is frozen. Thevalidate-expressfeature is on by default, so the npm package carries it. - Amended 2026-10-26 (#559, property-edit identity): the property edit's new sets and relationships derive their name-based
GlobalIdover a per-batch seed too: the seed, the object'sGlobalId, the set name, the role and a serial, never an entity id. Hosts draw the seed as for authoring: the operating system's on native targets,Math.randomin the browser. binding-core adds*_seededforms of the property, value and table writes; aGlobalIdthe model holds is refused withinvalid-value. - Amended 2026-10-27 (#465, undo and redo): each host exposes the model's history (ADR 0022):
set_history_limit,history,undo,redoandclear_history(setHistoryLimit,SetHistoryLimitand so on; Copenbim_ifc_v0_1_model_set_history_limit,_model_history,_model_undo,_model_redo,_model_clear_history). History is off by default (limit 0), because recording copies what a change replaces; with a limit, every public mutator of binding-core is one entry, found by a test that scans its source for&mut selfmethods, so a new mutator cannot go unrecorded. New codeshistory-empty(C 38), for an undo or redo with nothing to step through, andhistory-stale(C 39), for a model changed outside the history; a refusal changes nothing. The Cundoandredofollow the removal buffer protocol: a size query or a short buffer peeks and applies nothing. The C ABI becomes 0.1.23, withOpenbimIfcHistoryState; nov0_1symbol changes.
Alternatives considered
| Option | Why not |
|---|---|
| One crate exporting all three targets behind features | Each target pulls its own toolchain (wasm-bindgen, pyo3, cbindgen) and its own crate-type; mixing them makes every build pay for all three and every change risk all three. |
Bind the ifc-* crates directly | Duplicates the facade's feature selection per target and lets a binding bypass the layering rules the facade enforces. |
| Duplicate the model operations per host crate | Three copies of the validation drift apart; a value one host refuses, another would accept. |
| Python and WASM as thin layers over the C ABI | Adds a second unsafe boundary and a manual memory protocol to hosts that already have safe, idiomatic Rust binding generators. |
Map Value to plain host values (number, string, null) | Lossy: $/*, .U., int/real and typed wrappers do not survive. |
Consequences
Positive
- A consumer of any binding sees the same model the Rust facade does.
- Binding crates can version and release independently of the IFC crates.
- The layering rules keep holding: bindings are a new outermost layer.
Negative / costs
- The tagged
Valueencoding is more verbose than host-native values. - WASM builds need
wasm32-unknown-unknown-compatible dependencies; the gate checks this so a native-only dependency cannot slip in.
Follow-ups / risks to watch
- The C ABI is the one
unsafecrate; every dereference sits in itsbuffermodule with aSAFETYnote, as in Axiolid's ADR 0040. - Publication (npm, PyPI, a CMake package) is tracked separately under #34.
- npm publication needs a package name and registry credentials; until then the WASM package is built and tested but not published.
Relation to existing code
openbim-ifc-binding-core/(shared, host-independent)openbim-ifc-wasm/,openbim-ifc-capi/,openbim-ifc-py/openbim-ifc/(the only allowed dependency)ifc-model/tests/package_architecture.rs(enforces the dependency rule)