| name | ifc-impl-authoring-file |
| description | Use when authoring a new IFC file from scratch and the minimal valid skeleton must be built before any element can be added: the IfcProject context root, the IfcUnitAssignment, the IfcGeometricRepresentationContext, the spatial tree, the IfcOwnerHistory, the STEP header, and the first wall with geometry. Prevents the file failing to open or showing nothing in a viewer because units, the geometric context, or the spatial root are missing, because GlobalId values are regenerated on every export, or because FILE_SCHEMA does not match the entities used. Covers the mandatory setup sequence, the HEADER and FILE_SCHEMA, stable GlobalId generation, the project to site to building to storey chain wired with IfcRelAggregates, placing one IfcWall with IfcRelContainedInSpatialStructure, and the decision of which IFC version to target. Keywords: author IFC file, create IFC from scratch, minimal IFC file, IfcProject setup, IfcUnitAssignment, IfcOwnerHistory, IfcGeometricRepresentationContext, FILE_SCHEMA, GlobalId generation, IFC GUID, spatial tree, IfcRelAggregates, IfcRelContainedInSpatialStructure, IfcSite, IfcBuilding, IfcBuildingStorey, IfcWall, nothing shows in viewer, IFC file will not open, empty IFC model, how do I write an IFC file, what is the minimum valid IFC file, which IFC version should I use.
|
| license | MIT |
| compatibility | Designed for Claude Code. Requires IFC IFC2x3,IFC4,IFC4.3. |
| metadata | {"author":"OpenAEC-Foundation","version":"1.0"} |
Authoring an IFC File from Scratch
A valid IFC file is not just a header plus elements. Every physical
element depends on a mandatory skeleton: a context root, units, a
geometric frame, and a spatial tree. Omitting any part of that skeleton
makes every later element invalid or invisible. This skill teaches the
exact setup sequence, GlobalId generation, and a complete worked minimal
file containing one wall.
Verified against the buildingSMART IFC4.3 specification, the IFC4 ADD2
TC1 and IFC2x3 TC1 specifications, and the IFC Header Data Implementation
Guide v1.0.2. See references/methods.md for full entity signatures,
references/examples.md for copy-paste files per version, and
references/anti-patterns.md for what fails and why.
Quick Reference
The mandatory setup sequence
A file ALWAYS provides these seven things, in this order of dependency:
| Step | What | Why it is mandatory |
|---|
| 1 | STEP header with FILE_SCHEMA | Names the schema a reader dispatches on |
| 2 | IfcOwnerHistory (+ person, org, app) | Required in IFC2x3; expected by importers |
| 3 | IfcUnitAssignment of IfcSIUnit | Without units every measure is meaningless |
| 4 | IfcGeometricRepresentationContext | The 3D frame; without it geometry is unanchored |
| 5 | IfcProject (one only) | The context root that owns units and contexts |
| 6 | Spatial tree, wired with IfcRelAggregates | Project to Site to Building to Storey |
| 7 | Each element placed with IfcRelContainedInSpatialStructure | An uncontained element is an orphan |
NEVER add an IfcWall, IfcSlab, or any other element before steps 1
through 6 exist. The element will reference units, a context, and a
spatial container that are not there.
Entity name by version (hard renames)
| Concept | IFC2x3 | IFC4 | IFC4.3 |
|---|
FILE_SCHEMA value | IFC2X3 | IFC4 | IFC4X3 |
| Built-element supertype | IfcBuildingElement | IfcBuildingElement | IfcBuiltElement |
| Standard wall | IfcWallStandardCase | IfcWall (Std.Case deprecated) | IfcWall only |
IfcWall.PredefinedType | absent | present | present |
IfcOwnerHistory | mandatory | optional | optional |
IfcBuildingElement returns HTTP 404 in the IFC4.3 documentation: the
rename is file-breaking. ALWAYS pick entity names from the column that
matches your FILE_SCHEMA.
GlobalId rules
- A
GlobalId is a 22-character string encoding a 128-bit UUID with a
custom base64 alphabet (0-9, A-Z, a-z, _, $).
- The first character is ALWAYS one of
0, 1, 2, 3.
- ALWAYS generate it from a real 128-bit UUID, then compress to 22 chars.
- ALWAYS persist the
GlobalId with the logical object and reuse it on
every export of that object.
- NEVER regenerate a
GlobalId on each export: round-trip identity,
change tracking, and reference stability all depend on it staying.
Decision Trees
Which IFC version to target
Does the model contain infrastructure (bridge, road, rail, port, tunnel)?
├── YES -> target IFC4.3 (FILE_SCHEMA = IFC4X3)
│ Only IFC4.3 has IfcBridge / IfcRoad / IfcRailway / alignment.
└── NO -> Must the file open in older or certified-only software?
├── YES -> target IFC2x3 (FILE_SCHEMA = IFC2X3)
│ Widest compatibility; Coordination View 2.0.
│ OwnerHistory is MANDATORY here.
└── NO -> target IFC4 (FILE_SCHEMA = IFC4)
Default for buildings: tessellation, NURBS,
Reference View and Design Transfer View MVDs.
NEVER target IFC5 or IFCx for a production exchange: both are in
development and subject to change.
Which relationship attaches a thing to the tree
Is the thing a spatial element (Site, Building, Storey, Space)?
├── YES -> wire it to its parent with IfcRelAggregates
│ (RelatingObject = the whole, RelatedObjects = the parts).
└── NO -> it is a physical element (Wall, Slab, ...).
Attach it to exactly ONE spatial level with
IfcRelContainedInSpatialStructure
(RelatingStructure = the level, RelatedElements = the parts).
NEVER use IfcRelAggregates to put a wall into a storey, and NEVER use
IfcRelContainedInSpatialStructure to nest a storey under a building.
Swapping them produces a structurally valid but meaningless model.
Patterns
Pattern 1: the STEP header
ISO-10303-21;
HEADER;
FILE_DESCRIPTION(('ViewDefinition [ReferenceView_V1.2]'),'2;1');
FILE_NAME('minimal.ifc','2025-05-20T10:00:00',('OpenAEC'),
('OpenAEC Foundation'),'IFC authoring example',
'IFC authoring example','');
FILE_SCHEMA(('IFC4'));
ENDSEC;
DATA;
...
ENDSEC;
END-ISO-10303-21;
FILE_SCHEMA ALWAYS names the exact schema whose entities the DATA
section uses. implementation_level is ALWAYS '2;1' for IFC files.
See ifc-syntax-step-physical-file for the full header field semantics.
Pattern 2: ownership, units, geometric context
#1=IFCPERSON($,'Heijting','Freek',$,$,$,$,$);
#2=IFCORGANIZATION($,'OpenAEC Foundation',$,$,$);
#3=IFCPERSONANDORGANIZATION(#1,#2,$);
#4=IFCAPPLICATION(#2,'1.0','IFC Authoring Example','AUTHEX');
#5=IFCOWNERHISTORY(#3,#4,$,.ADDED.,$,$,$,1747699200);
#6=IFCSIUNIT(*,.LENGTHUNIT.,$,.METRE.);
#7=IFCSIUNIT(*,.AREAUNIT.,$,.SQUARE_METRE.);
#8=IFCSIUNIT(*,.VOLUMEUNIT.,$,.CUBIC_METRE.);
#9=IFCSIUNIT(*,.PLANEANGLEUNIT.,$,.RADIAN.);
#10=IFCUNITASSIGNMENT((#6,#7,#8,#9));
#11=IFCCARTESIANPOINT((0.,0.,0.));
#12=IFCAXIS2PLACEMENT3D(#11,$,$);
#13=IFCGEOMETRICREPRESENTATIONCONTEXT($,'Model',3,1.E-05,#12,$);
#14=IFCGEOMETRICREPRESENTATIONSUBCONTEXT('Body','Model',*,*,*,*,
#13,$,.MODEL_VIEW.,$);
IfcSIUnit is serialized as (*,.UNITTYPE.,prefix,.NAME.): the leading
* is the derived Dimensions slot. ALWAYS declare at least the length,
area, volume, and plane-angle units. The Body sub-context (#14) is
where SweptSolid geometry is placed.
Pattern 3: project and spatial tree
#15=IFCPROJECT('1aBcD2eFgH3iJkL4mNoP5q',#5,'Minimal Project',
$,$,$,$,(#13),#10);
#16=IFCLOCALPLACEMENT($,#12);
#17=IFCSITE('2qP5oNm4LkJi3HgFe2DcBa',#5,'Default Site',$,$,#16,$,$,
.ELEMENT.,$,$,$,$,$);
#18=IFCLOCALPLACEMENT(#16,#12);
#19=IFCBUILDING('3rStUvWxYz0AbCdEfGhIjK',#5,'Default Building',
$,$,#18,$,$,.ELEMENT.,$,$,$);
#20=IFCLOCALPLACEMENT(#18,#12);
#21=IFCBUILDINGSTOREY('0KjIhGfEdCbA0zYxWvUtSr',#5,'Ground Floor',
$,$,#20,$,$,.ELEMENT.,0.);
#22=IFCRELAGGREGATES('1LmNoPqRsTuVwXyZ012345',#5,$,$,#15,(#17));
#23=IFCRELAGGREGATES('2$abc_DEF123ghi456JKL7',#5,$,$,#17,(#19));
#24=IFCRELAGGREGATES('3MnOpQrStUvWxYz_$01234',#5,$,$,#19,(#21));
IfcProject.RepresentationContexts references the parent context #13,
NEVER the sub-context. The placement chain mirrors the tree: site
placement is absolute (PlacementRelTo is $), building relative to
site, storey relative to building.
Pattern 4: one wall with geometry
#25=IFCRECTANGLEPROFILEDEF(.AREA.,$,$,5.0,0.2);
#26=IFCDIRECTION((0.,0.,1.));
#27=IFCEXTRUDEDAREASOLID(#25,#12,#26,3.0);
#28=IFCSHAPEREPRESENTATION(#14,'Body','SweptSolid',(#27));
#29=IFCPRODUCTDEFINITIONSHAPE($,$,(#28));
#30=IFCLOCALPLACEMENT(#20,#12);
#31=IFCWALL('0aZ9bY8cX7dW6eV5fU4gT3',#5,'Wall 1',$,$,#30,#29,
'W-001',.SOLIDWALL.);
#32=IFCRELCONTAINEDINSPATIALSTRUCTURE('1hS2iR3jQ4kP5lO6mN7nM8',
#5,$,$,(#31),#21);
The profile (#25) is a 5.0 by 0.2 footprint; the extrusion (#27)
sweeps it 3.0 along +Z to produce the wall solid. The shape is placed in
the Body sub-context (#14). The wall ends up in the tree only because
#32 contains it in the storey #21. NEVER omit that relationship: an
uncontained element is an orphan and fails validation.
The full copy-paste file, plus IFC2x3 and IFC4.3 variants, is in
references/examples.md.
Pattern 5: version-specific wall
- IFC2x3: use
IFCWALLSTANDARDCASE with 8 attributes (no
PredefinedType); IfcOwnerHistory MUST NOT be $.
- IFC4: use
IFCWALL with 9 attributes ending in PredefinedType;
IfcWallStandardCase still exists but is deprecated.
- IFC4.3: use
IFCWALL only; IfcWallStandardCase was removed;
IfcWall is a subtype of IfcBuiltElement.
Reference Links
references/methods.md: full positional attribute signatures for every
entity used in the setup skeleton, per version.references/examples.md: complete copy-paste minimal files for IFC2x3,
IFC4, and IFC4.3.references/anti-patterns.md: the setup mistakes that make a file fail
to open, show nothing, or fail validation.
Related skills
ifc-syntax-step-physical-file: the .ifc STEP syntax, header fields,
token notation, and string escaping.ifc-core-spatial-structure: the spatial decomposition model, the
IfcProject context root, and containment versus reference.ifc-syntax-building-elements: the concrete physical entities and
their predefined-type enumerations.
Official sources
