| name | ifc-syntax-ifcjson |
| description | Use when reading, generating, or evaluating an ifcJSON file, choosing a JSON encoding for IFC data in a web or REST application, or resolving the ref-based cross-references in an ifcJSON document. Prevents treating ifcJSON as a stable standardized format, expecting lossless round-tripping, inlining referenced entities instead of using ref objects, and using the legacy IFCJSON-Team lineage instead of the current buildingsmart-community repo. Covers ifcJSON as a provisional candidate format for IFC4 and IFC4.3 : the top-level envelope, the data array of entity objects, camelCased attribute keys, the ref object that replaces the STEP id, file size, and the two ifcJSON lineages. Keywords: ifcJSON, IFC JSON, JSON encoding of IFC, ifcjson data array, ref object, globalId, camelCase IFC attributes, buildingsmart-community ifcJSON, provisional format, candidate format, IFC for web apps, IFC REST API, how do I read an IFC JSON file, convert IFC to JSON, IFC without EXPRESS, my ifcJSON will not round-trip, "ifcJSON file will not open", "data lost converting IFC to JSON", "ref points nowhere in ifcJSON", "which ifcJSON repo is current", what is an ifcJSON file, getting started with IFC JSON.
|
| license | MIT |
| compatibility | Designed for Claude Code. Requires IFC IFC4, IFC4.3. |
| metadata | {"author":"OpenAEC-Foundation","version":"1.0"} |
IFC Syntax : ifcJSON
PROVISIONAL FORMAT : subject to change. ifcJSON is a buildingSMART
Provisional / Candidate format. It has no ISO standard, no formal release, and no
guaranteed round-trip fidelity. ALWAYS treat ifcJSON as developmental and pin the exact
repository commit a project depends on. NEVER treat ifcJSON as a stable interchange
format on the level of the STEP Physical File or ifcXML.
ifcJSON is the JSON encoding of the IFC data model, aimed at developers building web and
JavaScript applications who have never used EXPRESS or STEP files. Like every IFC
encoding, it is derived from the EXPRESS schema : the schema is the single source of
truth, and ifcJSON is one projection of it.
Quick Reference
Format facts (verified)
| Property | ifcJSON value |
|---|
| File extension | .json |
| MIME type | application/json |
| ISO standard | none |
| Official status | Provisional / Candidate |
| Relative file size | 148% of the STEP Physical File (SPF = 100%) |
| Specification repo | buildingsmart-community/ifcJSON (the current lineage) |
| Schema synchronization | IFC4, developed toward IFC4.3 |
ifcJSON is the largest of the IFC text encodings : SPF is 100%, ifcXML 113%,
ifcJSON 148%. ifcZIP (17%) compresses whichever text payload it wraps.
Top-level envelope
An ifcJSON document is a single JSON object with a metadata envelope and a data array :
{
"type": "ifcJSON",
"version": "0.0.1",
"schemaIdentifier": "IFC4",
"originatingSystem": "...",
"preprocessorVersion": "...",
"timeStamp": "...",
"data": [ ... ]
}
type is the literal string "ifcJSON" : it identifies the document, NOT an IFC class.schemaIdentifier names the IFC schema version ("IFC4", "IFC4X3").data is an array of entity objects : the actual IFC population.
Entity object
Each element of data is one IFC instance :
{
"type": "IfcProject",
"globalId": "2fb45857-e9ac-4660-8943-604b07b54025",
"ownerHistory": { "type": "IfcOwnerHistory", "ref": "..." },
"name": "Project",
"representationContexts": [ ... ]
}
type is the IFC class name ("IfcProject", "IfcWall"), exact IFC casing.globalId is the instance identifier, written as a UUID string.- Every other key is an attribute name in camelCase : EXPRESS
OwnerHistory becomes
ownerHistory, RepresentationContexts becomes representationContexts.
The ref object (cross-reference)
ifcJSON does NOT use the SPF #id integer. A reference to another entity is a small
object carrying the referenced entity's type and its globalId under the key ref :
{ "type": "IfcOwnerHistory", "ref": "e4980768-d888-49ec-8297-0968dbd994ca" }
ALWAYS resolve a ref by matching its value against the globalId of an entity object
in the data array. The globalId is the cross-reference key, replacing SPF's #id.
The two ifcJSON lineages
| Lineage | Repos | Use |
|---|
| Current | buildingsmart-community/ifcJSON | ALWAYS target this one |
| Legacy | IFCJSON-Team (IFC.JSON-4, IFC.JSON-5Alpha) | NEVER target ; superseded |
Decision Trees
Should I use ifcJSON at all?
What is the consuming application?
|
+-- A web / JavaScript / REST application, developers unfamiliar with EXPRESS
| AND the project accepts a provisional, changeable format
| --> ifcJSON is a reasonable fit. Pin the buildingsmart-community repo commit.
|
+-- A long-term archive, a contractual deliverable, or cross-tool BIM exchange
| --> NEVER ifcJSON. Use the STEP Physical File (.ifc). It is the official,
| ISO 10303-21 baseline with universal tool support.
|
+-- An XML toolchain (XSLT, XPath, XSD validation)
--> Use ifcXML (.ifcXML), the official ISO 10303-28 encoding.
Resolve a ref object
Encountered an object with a "ref" key?
|
+-- Read its "ref" value : a globalId string.
| Read its "type" value : the expected IFC class.
|
+-- Search the data array for an entity object whose "globalId" equals the ref value.
| |
| +-- Found --> that entity object is the referenced instance.
| +-- Not found --> the document is incomplete or the reference is dangling.
| NEVER fabricate the missing entity.
Which repo / lineage to follow
Found ifcJSON sample code or a converter?
|
+-- From buildingsmart-community/ifcJSON --> current. Use it.
+-- From IFCJSON-Team (IFC.JSON-4, IFC.JSON-5Alpha) --> legacy. NEVER use.
+-- Unsure --> ALWAYS verify against buildingsmart-community/ifcJSON before relying on it.
Patterns
Pattern : Read the top-level envelope before the data
ALWAYS read type, schemaIdentifier, and the metadata keys before iterating data.
schemaIdentifier tells the reader which IFC schema version the entity objects conform
to, which determines valid class names and attributes. NEVER assume the schema version :
read it from schemaIdentifier.
The top-level type is the literal "ifcJSON". NEVER confuse it with an entity
object's type, which is an IFC class name.
Pattern : Read an entity object
Each entity object's type is the IFC class name in exact IFC casing (IfcWall, not
ifcwall or IFCWALL). Every attribute key is the EXPRESS attribute name lower-camel
cased : the first letter is lowercased, the rest of the EXPRESS PascalCase preserved
(Name to name, OwnerHistory to ownerHistory,
RepresentationContexts to representationContexts).
ALWAYS map a camelCase key back to its EXPRESS attribute by re-capitalizing the first
letter when checking the schema. NEVER assume an attribute key is absent because of a
casing mismatch.
Honour the IFC version renames. IfcBuildingElement (IFC4) was renamed
IfcBuiltElement in IFC4.3 ; an entity object's type reflects the schema named in
schemaIdentifier. See ifc-core-entity-hierarchy.
Pattern : Resolve references through globalId, never through position
ifcJSON has no positional #id. A reference is always a { "type": ..., "ref": ... }
object whose ref is the target entity's globalId. ALWAYS build a lookup map from
globalId to entity object in one pass over data, then resolve every ref against
that map.
NEVER inline a full entity where a ref belongs : duplicating an entity object instead
of referencing it breaks identity, because two inlined copies are two separate objects.
NEVER rely on array order in data : an entity may be referenced before it appears.
Pattern : Treat DERIVE and INVERSE attributes as absent
Like every IFC encoding, ifcJSON serializes only explicit attributes. DERIVE
attributes (computed) and INVERSE attributes (back-references) are NEVER keys in an
entity object. A reader recomputes DERIVE values from the schema and rebuilds INVERSE
relationships by indexing the forward ref objects. NEVER expect an INVERSE attribute
as a JSON key. See ifc-syntax-express.
Pattern : Do not assume lossless round-tripping
ifcJSON lists round-trip conversion as a design goal, but fidelity is not guaranteed :
the format is provisional and still being synchronized to IFC4.3. Converter options
(compact formatting, inverse-relationship handling, schema versioning) change the output.
ALWAYS keep the original STEP Physical File as the authoritative copy when ifcJSON is
produced by conversion. NEVER discard the SPF source on the assumption that
SPF to ifcJSON to SPF reproduces it exactly. What is at risk : instance identifiers,
the order of unordered aggregates, header metadata, and exact numeric formatting. The
model is preserved ; the byte-level file is not. See ifc-impl-format-transcoding.
Pattern : Pin the specification
ifcJSON has no formal release ; the sample envelope carries "version": "0.0.1". ALWAYS
record the exact buildingsmart-community/ifcJSON commit or tag a project was built
against, so a later specification change does not silently break the integration.
Reference Links
references/methods.md : the full ifcJSON document grammar : envelope keys, entity
object rules, the ref object, the camelCase mapping, the format-comparison table, and
the converter tooling.references/examples.md : verified ifcJSON fragments : a complete envelope, entity
objects, ref resolution, and the SPF-to-ifcJSON mapping.references/anti-patterns.md : the failure modes this skill prevents, each with the
reason it fails.
Official sources
Related skills
ifc-syntax-step-physical-file : the STEP Physical File (.ifc), the official baseline.ifc-syntax-ifcxml : the official ISO 10303-28 XML encoding.ifc-syntax-express : the EXPRESS schema, the single source of truth for all encodings.ifc-impl-format-transcoding : converting between IFC encodings.ifc-core-entity-hierarchy : IFC class names and the IfcBuiltElement rename.
