ifc-syntax-ifcjson

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

• ifcJSON specification repo : https://github.com/buildingsmart-community/ifcJSON
• ifcJSON sample : https://github.com/buildingsmart-community/ifcJSON/blob/main/Samples/IFC_4.0/BuildingSMARTSpec/air-terminal-element.json
• IFC file formats overview : https://technical.buildingsmart.org/standards/ifc/ifc-formats/

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.