# Ifc Syntax Ifcjson

> 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 fil

- Skill: `impertio-studio/ifc-syntax-ifcjson` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add impertio-studio/ifc-syntax-ifcjson`
- Raw SKILL.md: https://api.skillmd.com/api/skills/impertio-studio/ifc-syntax-ifcjson/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: MIT
- Author: Impertio-Studio (https://skillmd.com/u/impertio-studio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/impertio-studio/ifc-syntax-ifcjson

---


# 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 :

```json
{
  "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 :

```json
{
  "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` :

```json
{ "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.