SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsifc-impl-authoring-file

ifc-impl-authoring-file

Coding & development

View repository

Updated 10-15 22:18

About this skill

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