FreeCADWasmDev/docs/current/IFC_SEMANTIC_EXPORT_CONTRACT.md

IFC Semantic Export Acceptance

This is an additional user-authorized requirement, not a rename of the already passing geometric export contract. It remains unaccepted until current native execution evidence covers the required semantics. Keep all original 1507 requirements; the combined scope now contains 1508 requirements.

Required cases must cover both independent IFC input and newly authored native FreeCAD BIM objects. A synthetic proxy-only file is insufficient.

• Preserve product classes (wall, slab, column, opening/window/door where supported), stable GlobalIds and identifiers across repeated exports. Derive classes from real native IFC properties/schema, not labels or names. Include misleading labels and renamed labels as negative cases: a label containing "wall" must not convert an untyped shape to an IfcWall, and renaming a real wall must not change its class or GlobalId.
• Preserve project/site/building/storey hierarchy, containment, decomposition, nested placement and model units. Include translated/rotated geometry.
• Preserve typed property sets, quantities, material associations and classification data; change representative values and verify actual output.
• Export added/deleted objects and changed native geometry while keeping unchanged entities and relationships from imported IFC models.
• Verify output with the upstream IFC parser and native geometry checks, not regular-expression counts or a private JSON/BREP payload.
• Verify failed export preserves source state, transactions and destination bytes; reject unsupported semantic data explicitly instead of discarding it.

Reuse the local freecad-source/src/Mod/BIM/importers/exportIFC.py, exportIFCHelper.py, nativeifc, and the real IfcOpenShell source at freecad-source/build-web/ifcopenshell-native/source. Its parser, geometry and OCCT archives already exist. The source includes the SWIG wrapper and upstream Python API. Inspect their build integration before writing custom exporters.

The current IfcOpenShellNative.exportDocument provides solid geometry as IFC4 proxies. It is a working fallback, not evidence for this semantic contract. Do not replace or remove its existing passing cases. Extend the existing BIM business case contract with this exact capability ID and actual assertions.

Report the tested schema versions and unsupported fields explicitly. The user has not authorized silently excluding required classes/relationships to obtain a passing result. External blockers must remain recorded, with independent work continuing.

Each result case must declare a covers array naming the semantic areas it actually verifies, with actual output data in the case or assertions. All requiredProofAreas in the supplemental requirement are mandatory. The runner rejects incomplete area coverage even when individual assertions pass. Tags must correspond to real per-area comparisons; adding every tag to a proxy geometry sample does not meet this contract.

The runner separately executes tools/verify_ifc_semantic_export.mjs, which imports an independent official IFC file, exports it twice and compares the reparsed native identity, class, spatial hierarchy, property sets and volume. This verifier is independent of the implementation-owned case output and is hashed into the requirement. Do not modify the verifier or contract to bypass a failing implementation. The remaining proof areas still need their own real assertions; passing this core verifier alone is not full semantic acceptance.

First independent diagnostic (2026-09-16): source class and volume are retained, but GlobalIds change on each export, property sets disappear and hierarchy identities/relationships are not preserved. Evidence: business-evidence/266816da4ea763887c126a8a-20260916T004316642841.json. The earlier tag-only claimed pass is invalid and superseded by this failure.

Latest continuation: IFC_IDENTITY_PROGRESS.md. Product GlobalIds are now preserved and pass the independent repeated-export checks; property sets and spatial hierarchy still fail. Keep all other mandatory proof areas. The identity fix does not close this full semantic contract.