A lightweight, structured-design-friendly JSON schema for early-stage structural BIM data. Built for fast iteration in Grasshopper and computational design workflows.
日本語版 README | English
The MakeBuildingPro Schema (or MBP Schema) is an open JSON schema for representing structural building data in a way that is:
- Lightweight: ~50 top-level keys, fits in a single JSON file
- Computationally friendly: clean separation of member catalogs (definitions) and layouts (placements) — perfect for Grasshopper, Python, or any procedural workflow
- BIM-aware: integrates well with IFC, Revit families, Speckle, BHoM, and other industry-standard formats
- Carbon-conscious: every material entry carries a
CO2_Factor, enabling embodied-carbon analysis from the earliest design stage - Practical, not academic: designed by structural engineers who use it daily, reflecting real-world details like tapered beams, span-by-span rotations, and trailing slabs
It is the data format used by MakeBuildingPro, a Grasshopper plugin for parametric structural design — but the schema is fully open and tool-agnostic. Any application that wants to read or write lightweight structural data can use it.
Existing options have trade-offs:
| Format | Strength | Limitation |
|---|---|---|
| IFC (buildingSMART) | Industry standard | Heavy; structural data buried inside complex geometry/property hierarchies |
| ST-Bridge (Japan) | Domain-specific | Locale-bound; XML-heavy; limited international adoption |
| Tekla / Revit native | Tool-rich | Proprietary; vendor lock-in |
| Speckle | Modern, open | General-purpose; no structural-domain semantics |
| MBP Schema | Domain-clean + lightweight + open | Newer, smaller ecosystem |
MBP Schema fills the niche of "structural design data, just enough, in a format anyone can parse in five minutes" — ideal for early-stage iteration before committing to a full BIM authoring tool.
Catalog_* — Member definitions (sections, materials, connections)
Layout_* — Member placements (where they go in the building)
This separation matches how engineers think (catalogs first, then placements) and how computational tools work (looping over arrays).
Columns, Posts, Main Beams, Secondary Beams, Tertiary Beams, Cantilever Beams, Walls, Slabs, Cantilever Slabs, Braces, Wall Openings, Slab Openings, Isolated / Strip / Mat Foundations, Piles, Beam Point Loads, Beam Line Loads.
Secondary and tertiary beams support per-span variations of section type, slab type, Z-offset, and rotation — modeling tapered roofs, sloped floors, and twisted forms cleanly.
Both Japanese (Building Standards Act §85) and international (ASCE 7 / Eurocode 1) load conventions are first-class, alongside snow loads and load combinations.
Every Catalog_Material entry has an optional CO2_Factor, enabling
embodied-carbon estimation directly from the structural data.
pip install mbp-datafrom mbp_data import read_json, Validator
data = read_json("project.json")
print(data.summary())
result = Validator().validate(data)
if not result.is_valid:
for error in result.errors:
print(error)See python/README.md for full Python documentation.
The schema is plain JSON — any language with a JSON parser can use it.
The published JSON Schema (Draft 2020-12) is at
schemas/MakeBuildingPro_BuildingData_Schema_v5.0.1.json.
Validate a file using any standard tool, e.g.:
# Node.js with ajv
npx ajv-cli validate -s schemas/MakeBuildingPro_BuildingData_Schema_v5.0.1.json -d project.json
# Python with check-jsonschema
pipx run check-jsonschema --schemafile schemas/MakeBuildingPro_BuildingData_Schema_v5.0.1.json project.jsonmakebuildingpro-schema/
├── README.md # This file (English)
├── README.ja.md # Japanese version
├── LICENSE # MIT
├── SCHEMA.md # Full schema specification (English)
├── SCHEMA.ja.md # Schema specification (Japanese)
├── schemas/
│ └── MakeBuildingPro_BuildingData_Schema_v5.0.1.json
├── samples/
│ ├── tiny_office.json # Minimal 1-story example
│ └── cascade_twist_3F.json # Full v5.0.1 feature showcase
├── python/ # Python reference parser (mbp-data package)
│ ├── README.md
│ ├── pyproject.toml
│ ├── mbp_data/
│ └── tests/
└── docs/ # Additional documentation
The MBP Schema is designed to complement, not replace existing standards.
| Integration | Status | Notes |
|---|---|---|
| IFC4 / IFC4.3 | Mappable | Most members map cleanly to IfcColumn / IfcBeam / IfcSlab / IfcWall / IfcFooting / IfcPile |
| ISO 19650 | Compatible | Project metadata is preserved; LOD-style status fields planned for v6.0 |
| Speckle | Adapter planned (v5.2) | Stream-based real-time exchange |
| BHoM | Adapter planned (v5.3) | BHoMObject conversion |
| Karamba3D | Adapter planned (v5.3) | Grasshopper-native structural analysis |
| Open BIM | Aligned with values | Lightweight, vendor-neutral, MIT-licensed |
| Version | Focus | Highlights |
|---|---|---|
| v5.0.1 | Current stable | Strip Foundation, parent-resolved openings, 18 layout types |
| v5.0.2 | Patch | Bug fixes, English UI strings, sample expansion |
| v5.1 | Public release | This GitHub repository, English documentation, Python parser |
| v5.2 | AI + Speckle | Natural-language building generator (BYOK), Speckle adapter |
| v5.3 | Adapters + Core/MBP separation | BHoM, Karamba3D adapters; drawing config separated from core schema |
| v6.0 | Internationalization | Member-type unification, locale-prefixed extension fields |
| v7.0+ | Standardization | Industry-body collaboration, language extensions |
For details, see docs/ROADMAP.md (coming soon).
We follow semantic versioning for the schema:
- Major (
vN.0.0): breaking changes (field removals, type changes) - Minor (
vN.M.0): additive changes (new optional fields, new layouts) - Patch (
vN.M.P): clarifications and fixes only
JSON files declare their schema version in the version field.
Forward-compat is maintained via additionalProperties: true in the schema —
unknown properties are preserved on round-trip.
Contributions are welcome! We are in early stages, so please:
- Open an issue first for bugs, schema gaps, or proposals
- Use GitHub Discussions for questions, ideas, and broader conversations
- Pull requests for documentation improvements, sample additions, or Python parser fixes are appreciated
Larger schema changes (new top-level fields, semantic shifts) require discussion in an issue before a PR. See CONTRIBUTING.md (coming soon) for details.
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Author: @dta-tutorials
MIT — Use this schema freely in any project, commercial or otherwise.
Related projects
- MakeBuildingPro — the Grasshopper plugin that produces and consumes MBP Schema files
- mbp-data (Python) — the reference parser library
If you build something with MBP Schema, we'd love to hear about it. Open a
discussion or share on social media with #MakeBuildingPro.