ifc-syntax-ifcxml

name	ifc-syntax-ifcxml
description	Use when you need to read, write, or recognise an ifcXML file, understand the iso_10303_28 / uos document structure, or resolve id / ref / href references in IFC XML data. Prevents confusing ifcXML (ISO 10303-28) with the STEP Physical File (ISO 10303-21), hand-authoring the XSD instead of generating it, ignoring the version-specific Part 28 configuration file, and mishandling the by-reference versus by-containment duality. Covers the ifcXML XML encoding, ISO 10303-28, the Part 28 configuration file, the iso_10303_28 root and single uos element, entity-to-element mapping, id / ref / href references, and when to choose ifcXML over SPF. Keywords: ifcXML, .ifcXML, IFC XML, ISO 10303-28, Part 28 configuration file, iso_10303_28, uos, unit of serialization, id ref href, xsi:nil, by-reference, by-containment, XSD validation, XSLT, XPath, how do I open an ifcXML file, ifcXML vs ifc, what is ifcXML, IFC XML schema, ifcXML file too large, "ifcXML will not validate", "href reference not resolving", "ifcXML opened as plain ifc", "XSD does not match my ifcXML", getting started with IFC XML, why is my ifcXML so big.
license	MIT
compatibility	Designed for Claude Code. Requires IFC IFC2x3, IFC4, IFC4.3.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

IFC Syntax : ifcXML

ifcXML is the XML encoding of an IFC model. It is one serialization of the same EXPRESS schema that the STEP Physical File (.ifc) encodes : the model is identical, only the presentation differs. This skill covers the ifcXML document structure, its governing standard (ISO 10303-28), and the rules for reading and writing IFC data as XML.

Quick Reference

What ifcXML is

• ifcXML is the XML serialization of an IFC model. File extension .ifcXML, MIME type application/xml.
• ifcXML is governed by ISO 10303-28 ("XML representation of EXPRESS schemas and data"). This is a different standard from ISO 10303-21, which governs the STEP Physical File .ifc format.
• The ifcXML XSD is generated, not hand-authored : it is produced from the IFC EXPRESS schema according to the ISO 10303-28 mapping rules.
• ifcXML applies to IFC2x3, IFC4, and IFC4.3 : each IFC version has its own generated XSD and its own published Part 28 configuration file.
• ifcXML is about 113% of the SPF file size (SPF = 100%).

The document skeleton

An ifcXML document ALWAYS has this two-level root structure :

<iso_10303_28>            <!-- exactly one, the Part 28 root -->
  <uos>                   <!-- exactly one child, the unit of serialization -->
    <IfcProject id="i1"> ... </IfcProject>
    <IfcWall id="i42"> ... </IfcWall>
    ...
  </uos>
</iso_10303_28>

• The root element is iso_10303_28, in the ISO 10303-28 namespace.
• It contains exactly one child element uos (unit of serialization), in the IFC-schema-specific namespace.
• There is exactly one uos per ifcXML file.
• Each IFC entity instance becomes an XML element named after the entity : <IfcWall>, <IfcComplexProperty>, <IfcPropertySingleValue>.

References : id, ref, href

• An instance is defined once with an id attribute (for example id="i87").
• Elsewhere it is referenced with a ref or href attribute carrying that id, plus xsi:nil="true" to mark the element as a pointer rather than a definition.
• The same model can be written by-reference (children referenced by href) or by-containment (children nested inline). Both encode the same EXPRESS population.

DERIVE and INVERSE attributes

ifcXML, like every IFC encoding, NEVER serializes DERIVE or INVERSE attributes. A reader recomputes them from the schema and the forward references. NEVER expect a derived or inverse value to appear in an ifcXML file.

Decision Trees

Pick the encoding : SPF or ifcXML

What does the consuming workflow need?
|
+-- Widest tool compatibility, smallest text file, fast line-oriented parse
|   --> STEP Physical File (.ifc). See ifc-syntax-step-physical-file.
|
+-- Integration with an XML toolchain (XSLT transforms, XPath queries,
|   XSD schema validation), or XML-native readability
|   --> ifcXML.
|
+-- Smallest possible transfer size
    --> ifcZIP wrapping either encoding. See ifc-syntax-step-physical-file.

ALWAYS treat ifcXML and SPF as interchangeable at the model level : choosing ifcXML is a tooling decision, NEVER a data-content decision.

Writing ifcXML : by-reference or by-containment

What is the writer's priority?
|
+-- Smallest file, no duplicated subtrees, shared objects referenced once
|   --> By-reference : define each object once with id, point with href.
|
+-- Simplest to read by eye, self-contained subtrees
|   --> By-containment : nest child objects inline.
|
+-- An object is referenced by more than one parent
    --> By-reference is REQUIRED : an object with one identity NEVER gets
        two inline definitions.

Is this file ifcXML or an SPF .ifc file?

Inspect the first bytes of the file.
|
+-- Starts with <?xml ...?> and an <iso_10303_28> root element
|   --> ifcXML. Parse with an XML parser.
|
+-- Starts with ISO-10303-21; and has HEADER / DATA sections
    --> STEP Physical File. Parse with an SPF parser.
        See ifc-syntax-step-physical-file.

NEVER decide the encoding from the file extension alone : ALWAYS confirm from the content.

Patterns

Pattern : Recognise ifcXML by its root structure

ALWAYS verify an ifcXML file by its document structure, not its extension :

• The XML declaration <?xml version="1.0" ...?>.
• A single root element iso_10303_28.
• Exactly one uos child element.

If a file claims to be ifcXML but has no iso_10303_28 root, it is NOT a conformant ifcXML document. NEVER assume any XML file containing <IfcWall> elements is valid ifcXML : the Part 28 envelope is mandatory.

Pattern : Treat the ifcXML schema as generated, governed by ISO 10303-28

The ifcXML XSD is derived from the IFC EXPRESS schema by the ISO 10303-28 mapping rules. The EXPRESS schema is the single canonical model; the XSD is an output of it.

• ALWAYS cite ISO 10303-28 for ifcXML, NEVER ISO 10303-21 (that is SPF).
• NEVER hand-author or hand-edit the ifcXML XSD : it is generated. Edits to the XSD desynchronise it from the EXPRESS schema.
• ALWAYS use the buildingSMART-published XSD for the exact target IFC version (IFC2x3, IFC4, or IFC4.3). The XSD differs per version because the EXPRESS schema differs per version.

See ifc-syntax-express for the EXPRESS schema and ifc-core-data-model for why the EXPRESS schema is canonical.

Pattern : Honour the version-specific Part 28 configuration file

The EXPRESS-to-XSD mapping of ISO 10303-28 is not always deterministic : one EXPRESS construct can map to several valid XSD shapes. A Part 28 configuration file resolves that choice.

• For IFC, the Part 28 configuration file is standardized and published for each IFC schema version.
• With IFC4, buildingSMART made more extensive use of the configuration capabilities to reduce the overhead of the default XML binding. ALWAYS expect the IFC4 and IFC4.3 ifcXML binding to differ from the IFC2x3 binding.
• ALWAYS pair an ifcXML file with the configuration file for its declared IFC version. NEVER assume a single binding applies across versions.

Pattern : Resolve id, ref, and href references

ifcXML expresses cross-references through XML attributes :

• A definition carries id="i87". The id is unique within the document.
• A reference carries ref="i87" or href="i87" plus xsi:nil="true".
• xsi:nil="true" marks the element as a pointer with no inline content.

ALWAYS resolve a ref / href to the element that owns the matching id before reading the referenced data. NEVER read an xsi:nil="true" element as if it held the object's attributes : it is a pointer, and the attributes live on the id-bearing definition.

The ifcXML id is a document-local string, NOT the IFC GlobalId and NOT the SPF #id integer. NEVER carry an ifcXML id across files or treat it as a stable identity : it is regenerated on every serialization.

Pattern : Choose by-reference or by-containment deliberately

ifcXML allows the same model to be written two ways :

• By-reference : each object is defined once with an id; parents point to it with href + xsi:nil="true". Smaller file, no duplicated subtrees.
• By-containment : child objects are nested inline inside their parent. Larger file, simpler to read, self-contained subtrees.

The ifcXML Implementation Guide frames this as a trade-off between Size, Simplicity, and Speed.

• ALWAYS use by-reference when an object is shared by more than one parent : an object has one identity and NEVER gets two separate inline definitions.
• A reader MUST support both forms : a conformant ifcXML file mixes them.
• NEVER assume a child element is always inline : it may be an href pointer.

Pattern : Map IFC entities and attributes to XML

• Each IFC entity instance is an XML element named exactly after the entity : <IfcWall>, <IfcComplexProperty>. ALWAYS use the entity name that matches the file's IFC version (for IFC4.3, IfcBuiltElement; for IFC2x3 and IFC4, IfcBuildingElement). See ifc-core-version-evolution.
• Explicit attributes become child elements or XML attributes, per the Part 28 binding.
• An unset OPTIONAL attribute is represented by the absence of the element, NOT by a $ token : $ is SPF syntax and NEVER appears in ifcXML.

Reference Links

• references/methods.md : the ifcXML fact sheet, ISO 10303-28 detail, the Part 28 configuration file, the document model, the reference mechanism, and the version-specific namespace.
• references/examples.md : worked ifcXML : the document skeleton, the verified by-reference snippet, the by-containment alternative, encoding detection.
• references/anti-patterns.md : the ifcXML mistakes this skill prevents, each with the reason it fails.

Official sources

• IFC file formats : https://technical.buildingsmart.org/standards/ifc/ifc-formats/
• ifcXML Implementation Guide v2.0 : https://technical.buildingsmart.org/wp-content/uploads/2018/05/ifcXML-Implementation-Guide-v2-0.pdf
• ISO 10303-28 : https://www.iso.org/standard/40646.html

Related skills

• ifc-syntax-step-physical-file : the STEP Physical File .ifc encoding.
• ifc-impl-format-transcoding : converting between SPF, ifcXML, and ifcJSON.
• ifc-syntax-ifcjson : the provisional JSON encoding.
• ifc-syntax-express : the EXPRESS schema that all encodings derive from.
• ifc-core-version-evolution : version-specific entity names and bindings.