Building Definition Language

112. Human-Readable BDL

Human-Readable BDL shall allow engineers, architects, manufacturers, inspectors, software developers, and other authorized users to inspect and author building definitions without reading a low-level database representation.

The human-readable form shall provide:

clear Entity declarations;

explicit Types;

explicit units;

readable references;

structured nesting;

comments;

descriptive names;

formatted constraints;

source-location reporting;

understandable validation messages.

Example:

structural_member Beam_B01 : TimberBeam {

id: "s05:member:beam-b01";

material: @Timber_GL24_Batch_021;

section {

width: 140 mm;

depth: 240 mm;

}

length: 3600 mm;

end_a: @EndCartridge_EC01;

end_b: @EndCartridge_EC02;

}

Human-readable names shall not replace persistent IDs.

Authoring tools may display translated labels while preserving the authoritative BDL identifiers:

}

Comments shall assist understanding but shall not contain information required for engineering interpretation.

Important assumptions, restrictions, and requirements shall be represented through typed declarations rather than informal notes.

Human-readable formatting may vary without changing semantics. Whitespace, indentation, and comments shall not affect the Canonical Representation.

113. Machine-Readable BDL

Machine-Readable BDL shall provide deterministic access to every Entity, Property, Relationship, Constraint, Profile, Evidence record, and configuration state.

It shall support:

unambiguous parsing;

schema validation;

identity resolution;

unit checking;

relationship traversal;

change comparison;

automated compilation;

API exchange;

BIOS configuration;

Digital Twin synchronization;

AI analysis;

A quantity shall not be exchanged as an untyped string:

{

}

A Reference shall identify its target explicitly:

{

"reference": "s05:node:n01"

}

Machine-readable BDL shall distinguish:

missing;

null;

unknown;

TBD;

not applicable;

withheld;

unverified.

Machine-readable serialization shall preserve:

source identity;

configuration version;

Profile version;

provenance;

access classification;

integrity information.

A machine-readable file that is syntactically correct but semantically unresolved shall not be represented as valid BDL.

114. Canonical Representation

The Canonical Representation shall provide one normalized, deterministic representation of a resolved BDL configuration.

It shall be used for:

integrity hashing;

digital signatures;

version comparison;

reproducible compilation;

package verification;

archival;

authoritative exchange.

Canonicalization shall include:

full namespace expansion;

normalized persistent IDs;

resolved Module versions;

explicit Type identifiers;

explicit units;

normalized numeric representation;

normalized dates and timestamps;

deterministic property ordering;

deterministic collection ordering where order has no semantic meaning;

removal of comments and display formatting;

explicit representation of unknown and optional values;

normalized relationship direction;

declared character encoding.

Example human-readable input:

length: 3.6 m;

may be canonically represented as:

{

}

The authoritative conversion unit shall be defined by the BDL Core Schema.

Canonicalization shall not remove meaningful original values, units, provenance, uncertainty, or evidence. Original authoring information may be retained alongside normalized values.

Two semantically identical valid BDL documents shall produce the same Canonical Representation when resolved against the same Module and Profile versions.

The standard format classes shall include:

BDL Text (.bdl) Human-readable authoring format using typed declarations, blocks, references, expressions, and constraints.

BDL JSON (.bdl.json) Structured machine-readable format suitable for APIs, inspection, debugging, and broad software interoperability.

BDL Package (.bdlp) Controlled package containing BDL Modules, resources, schemas, geometry, evidence references, signatures, and a package Manifest.

BDL Binary (.bdlb) Optional compact machine representation for high-performance local processing, BIOS deployment, robotics, or constrained devices.

All formats shall preserve equivalent core semantics.

The serialization declaration shall identify:

format;

format version;

BDL Core version;

character encoding;

canonicalization method;

compression where applicable;

package integrity.

Example:

serialization {

format: BDL_Text;

format_version: "1.0";

encoding: UTF_8;

bdl_core: "1.0";

}

Binary or compressed formats shall not become the sole archival representation.

A compliant tool shall identify unsupported format or schema versions explicitly rather than attempting uncertain interpretation.

The Schema shall define:

Core Entity Types;

primitive Types;

engineering quantity Types;

required and optional Properties;

relationship Types;

cardinalities;

unit dimensions;

permitted values;

lifecycle states;

configuration Types;

evidence structures;

extension points;

validation rules.

The Schema architecture shall include:

BDL Core Schema;

domain schemas;

Profile schemas;

extension schemas;

manufacturer schemas;

project schemas.

Example schema concept:

schema_type StructuralInterface {

extends: Interface;

required properties {

compatibility_class: CompatibilityClassRef;

coordinate_system: CoordinateSystemRef;

datum_system: DatumSystemRef;

transferred_actions: Set<StructuralAction>;

}

required relationships {

hosted_by: exactly_one<Component>;

}

}

Each Schema shall declare:

Schema ID;

namespace;

version;

publisher;

compatible BDL Core versions;

imported schemas;

status;

A schema change that alters required Properties, Type meaning, relationship cardinality, or safety interpretation shall receive compatibility review.

BDL projects shall use a controlled structure that separates Modules while preserving one authoritative Building Manifest.

A typical project structure may include:

The package Manifest shall identify:

Package ID;

Building ID;

package version;

BDL Core version;

entry document;

included files;

file roles;

integrity hashes;

external dependencies;

signatures;

access classifications;

creation tool;

Package extraction shall not be required for semantic identity. File paths shall not replace persistent Entity IDs.

A package may contain restricted sections. Their absence from a redacted distribution shall be declared rather than silently omitted.

Library categories may include:

Core language library;

structural library;

spatial library;

Interface library;

Cartridge library;

utility library;

safety library;

robotics library;

regional library;

manufacturer library;

project library.

Every Library item shall define:

persistent Type ID;

namespace;

version;

purpose;

parameters;

required Properties;

Interfaces;

constraints;

applicable Profiles;

evidence status;

publisher;

deprecation status.

Example:

width: Width;

height: Height;

}

];

}

}

Template instantiation shall create new Instance IDs while preserving the Template ID and version.

A Library update shall not silently change existing building configurations. Configurations shall retain their original version references until migration is approved.

Library content may be open, certified, experimental, regional, or proprietary. Its status shall be machine-readable.

119. Component and Cartridge Libraries

Component and Cartridge Libraries shall provide standardized, searchable definitions for products and reusable engineering Types.

Each Library entry shall include, as applicable:

Type ID;

manufacturer;

product family;

version;

classification;

controlled geometry;

external dimensions;

mass;

center of gravity;

materials;

Interfaces;

Capability Declaration;

requirements;

compatibility classes;

applicable Profiles;

lifecycle requirements;

Digital Passport template;

certification;

evidence;

availability status.

Example:

library_entry KitchenServiceCartridge_Type_02 {

type_id: "s05:cartridge-type:kitchen-service-02";

classification: functional_utility_hybrid;

form_factor: @Kitchen_Cartridge_Form_02;

];

certification: @KitchenCartridge_Type02_Certification;

}

Library search shall support engineering filters such as:

Interface Profile;

capacity;

geometry;

regional approval;

environmental class;

certification;

manufacturer;

lifecycle;

Withdrawn or recalled Types shall remain discoverable for lifecycle management but shall carry explicit restrictions.

120. Profile Libraries

Profile Libraries shall contain reusable Interface, Engineering, Regional, manufacturing, inspection, cybersecurity, and robotic Profiles.

Each Profile entry shall include:

Profile ID;

Profile Type;

issuing authority;

version;

scope;

inheritance;

mandatory requirements;

recommended requirements;

optional provisions;

prohibited conditions;

validation rules;

evidence requirements;

geographic or application limitations;

effective dates;

status.

Example:

];

}

Profile inheritance shall be explicit:

}

Recommended non-mandatory Profiles may be published to support regions and manufacturers with limited engineering resources.

AI-generated candidate Profiles shall be stored separately from approved Profiles and marked as requiring engineering review.

Authoring capabilities should include:

syntax highlighting;

structured Entity creation;

Type-aware completion;

unit checking;

reference resolution;

identity management;

schema validation;

Profile selection;

constraint feedback;

geometric linking;

graph editing;

configuration comparison;

provenance recording;

signature workflow;

access classification.

Tools shall display the difference among:

required;

optional;

unknown;

TBD;

assumed;

unverified;

noncompliant.

An authoring tool shall not silently:

change units;

replace identities;

update Library versions;

resolve conflicts;

select substitutions;

accept noncompliance;

AI-assisted authoring shall identify generated content and preserve:

source inputs;

AI model or service;

generation time;

review status;

Visualization types may include:

2D plans;

sections;

elevations;

3D building views;

structural topology;

Interface maps;

Cartridge maps;

utility networks;

dependency graphs;

state diagrams;

lifecycle timelines;

configuration comparisons;

compliance heat maps;

robotic envelopes.

Visualization shall distinguish:

physical geometry;

reference geometry;

service envelopes;

exclusion zones;

topology without geometry;

inferred information;

unresolved information;

noncompliance;

Selecting a Node graphically should allow retrieval of:

Node Type and Instance;

Interface Faces;

connected Cartridges;

capacity and demand;

state;

evidence;

A graphical move, deletion, or connection shall generate a proposed BDL change and pass validation before acceptance.

Simplified display geometry shall not be used for manufacturing or robotic operations unless approved for that purpose.

123. Engineering Compiler Integration

The Engineering Compiler shall transform BDL source into validated, resolved, and purpose-specific engineering outputs.

The Compiler shall receive:

Building Manifest;

BDL Modules;

Schemas;

Profiles;

Libraries;

geometry references;

constraints;

evidence;

target output definition.

Compilation stages shall include:

lexical parsing;

syntax validation;

namespace resolution;

Module and version resolution;

Type checking;

unit validation;

identity validation;

relationship validation;

Profile application;

constraint evaluation;

topology analysis;

compatibility validation;

dependency validation;

evidence checking;

output generation.

Compiler outputs may include:

validated Canonical BDL;

Building BIOS configuration package;

configuration validation report;

unresolved-item report;

manufacturing package;

assembly package;

robotic task definition;

Digital Twin initialization package;

human-readable engineering report.

A successful compilation shall mean only that the BDL satisfies the implemented rules and available evidence for the declared target.

The Compiler shall not replace professional engineering judgment, testing, certification, or regulatory approval.

The BIOS deployment package shall contain:

Building ID;

Configuration ID;

Component and Cartridge Registries;

Interface Registry;

Spatial Registry;

Capability Registry;

topology;

dependencies;

Profiles;

state models;

transition rules;

permissions;

commissioning requirements;

evidence references;

signatures.

The integration sequence shall be:

author BDL;

validate BDL;

compile configuration;

review and approve;

sign deployment package;

import into Building BIOS;

discover physical Instances;

reconcile design and physical conditions;

commission;

Runtime BIOS information shall include:

current installed Instances;

actual Interface connections;

active configuration;

states;

events;

faults;

maintenance;

operational changes.

Verified BIOS changes may generate BDL change sets for As-Installed, As-Operated, As-Maintained, or As-Modified records.

The Digital Twin shall use BDL to understand:

Entity identities;

Types;

spatial relationships;

geometry references;

Component and Cartridge composition;

Interface connections;

topology;

capabilities;

dependencies;

configuration stages;

evidence;

lifecycle states.

The Digital Twin shall receive operational updates from Building BIOS, including:

verified physical configuration;

Component and Interface states;

Cartridge replacements;

faults;

maintenance events;

operational limits;

configuration revisions.

The relationship shall be:

Digital Twin predictions shall return to BIOS or BDL as proposed or inferred information, not as automatically verified physical truth.

Each Digital Twin object shall reference the persistent BDL or BIOS Entity ID.

Geometric Twin objects without BDL identity shall remain unbound and shall not participate in authoritative compatibility or lifecycle decisions.

AI use cases may include:

natural-language-to-BDL authoring;

design alternative generation;

Profile generation;

Component selection;

compatibility analysis;

requirement extraction;

configuration checking;

risk identification;

maintenance planning;

engineering explanation;

legacy-model conversion.

AI-generated BDL shall include:

generating AI identity;

model or service version;

source inputs;

generation time;

assumptions;

confidence;

validation status;

human reviewer;

acceptance status.

Example:

provenance AI_Generated_Layout_001 {

subject: @Layout_Alternative_03;

generated_by: @System05_Design_AI;

model_version: "3.2";

source_inputs: @Owner_Requirements_001;

status: proposed;

engineering_review: required;

}

AI shall not silently:

assign verified status;

create certification;

resolve unknown safety data;

approve Profile exceptions;

alter signed configurations;

issue BIOS commands through BDL.

The Engineering Compiler shall validate AI-generated BDL using the same rules applied to human-authored content.

127. Robotic Systems Integration

BDL shall provide robots with structured definitions of physical Entities, task requirements, Interfaces, geometry, tolerances, access, and verification.

Robotic BDL outputs may include:

Entity identity;

target pose;

coordinate transformations;

grasp zones;

prohibited contact zones;

approach envelopes;

exclusion envelopes;

mass and center of gravity;

Interface protocol;

force and torque limits;

tool requirements;

temporary works;

expected final state;

evidence requirements.

Example:

robotic_task Install_WallPanel_WP01 {

handled_entity: @Wall_Panel_WP01;

target_location: @WP01_Final_Placement;

robot_profile: @Panel_Installation_Robot_Profile;

];

];

}

Robotic results shall return as structured evidence containing:

robot identity;

tool identity;

task version;

observations;

trajectory reference;

forces and torques;

final pose;

verification results;

BDL APIs shall enable controlled access to language resources, configurations, Libraries, Profiles, validation services, and change workflows.

API domains may include:

Entity API;

Type and Schema API;

Registry API;

Library API;

Profile API;

Configuration API;

Validation API;

Compiler API;

Evidence API;

Change Set API;

Query API;

Digital Twin exchange API;

BIOS deployment API.

Every API operation shall define:

requesting identity;

authorization;

target Entity or configuration;

BDL and Schema version;

input format;

output format;

validation level;

error behavior;

audit requirements.

Example query:

GET /bdl/configurations/house-001/entities/node-n01

Example validation request:

{

]

}

Import sources may include:

CAD;

BIM;

GIS;

spreadsheets;

structural-analysis models;

energy models;

product catalogs;

sensor databases;

asset-management systems;

manufacturing systems.

The import process shall define:

source format;

source version;

source coordinate system;

source units;

mapping rules;

identity strategy;

imported geometry;

imported semantics;

unsupported content;

uncertainty;

provenance.

Imported data shall be classified as:

mapped directly;

transformed;

approximated;

inferred;

unsupported;

requiring review.

Export targets may include:

geometry models;

schedules;

engineering reports;

manufacturing files;

BIOS packages;

Digital Twin packages;

robotic task packages;

Round-trip conversion shall not be claimed unless identity, units, relationships, constraints, and configuration status remain demonstrably preserved.

130. Legacy Model Conversion

Legacy Model Conversion shall transform existing drawings, BIM models, spreadsheets, databases, and undocumented asset records into provisional BDL.

The conversion process shall include:

inventory source files;

identify formats and versions;

determine coordinate systems and units;

extract geometry;

identify candidate Entities;

assign provisional identities;

map available Properties;

infer candidate Relationships;

identify missing Interfaces;

record unknown information;

attach provenance;

require human and engineering review.

Example:

legacy_conversion Existing_Building_Import_01 {

source: resource("existing-building-model.ifc");

source_version: "unknown";

coordinate_system: inferred(@Legacy_Project_CS);

unit_system: verified(mm);

generated_entities: @Legacy_Entity_Set_01;

unresolved_items: @Legacy_Conversion_Issues_01;

status: provisional;

}

Converted Entities shall distinguish:

directly verified source data;

mapped data;

inferred classification;

generated geometry;

unknown capability;

Physical inspection, measurement, testing, identity assignment, and engineering validation shall progressively upgrade provisional legacy records.

The original source files, conversion mappings, tool version, assumptions, and review decisions shall remain preserved.