Input JSON Specification¶

This page describes the input JSON accepted by Builelib. When creating or validating input JSON in another program, refer to the following three files.

File	Purpose
`src/builelib/input/inputdata/webproJsonSchema.json`	JSON Schema for validating structure, types, required fields, numeric ranges, and fixed options
`src/builelib/input/inputdata/input_options.json`	Lists of database-derived input options
`docs-md/chB_InputJson.mdlang`	Human-readable source for this page

The same information and validation are available from the Builelib API through /schema, /options, and /validate.

Authoritative Sources¶

The machine-readable source of truth for the input JSON is webproJsonSchema.json. It uses JSON Schema Draft-07 and can be used with general-purpose validation libraries such as jsonschema.

Options generated from the database—including building uses, room uses, orientations, and equipment methods—are provided in input_options.json. Check both the fixed enum values in the schema and the database-derived options when validating input in another program.

SpecialInputData is an optional extension area. Its detailed structure is not fixed because it may evolve as Builelib-specific functions are added.

Top-level Structure¶

The input JSON is an object with the following top-level sections.

Key	Required	Purpose
`Building`	Yes	Basic information for the whole building
`Rooms`	Yes	Rooms in the building
`EnvelopeSet`	No	Envelope composition and opening assignments
`WallConfigure`	No	Insulation specifications for walls and roofs
`WindowConfigure`	No	Window specifications
`ShadingConfigure`	No	Shading specifications
`AirConditioningZone`	No	Air-conditioning zones
`HeatsourceSystem`	No	Heat-source systems
`SecondaryPumpSystem`	No	Secondary-pump systems
`AirHandlingSystem`	No	Air-handling systems
`VentilationRoom`	No	Rooms served by ventilation
`VentilationUnit`	No	Ventilation equipment
`LightingSystems`	No	Lighting systems
`HotwaterRoom`	No	Rooms served by hot-water systems
`HotwaterSupplySystems`	No	Hot-water supply systems
`Elevators`	No	Elevators
`PhotovoltaicSystems`	No	Photovoltaic systems
`CogenerationSystems`	No	Cogeneration systems
`SpecialInputData`	No	Builelib-specific extended input
`CalculationMode`	No	Calculation mode, SP-sheet flags, and primary-energy conversion factors

At minimum, Building and Rooms are required. Add the corresponding sections for each type of equipment to be calculated.

{
  "Building": {
    "Name": "Sample Building",
    "Region": "6",
    "AnnualSolarRegion": "A3",
    "BuildingFloorArea": 1000.0
  },
  "Rooms": {
    "1F_Office": {
      "buildingType": "事務所等",
      "roomType": "事務室",
      "roomArea": 100.0
    }
  }
}

The option values in this example remain Japanese because they must match the values defined by WEBPRO and Builelib.

IDs and References¶

Many sections are objects keyed by user-defined IDs. For example, "1F_Office" may be a room ID in Rooms, while "PV_A" may be an equipment ID in PhotovoltaicSystems.

These IDs are referenced from other sections. The principal dependencies include:

Section	Prerequisite sections
`EnvelopeSet`	`Building`, `Rooms`, `WallConfigure`, `WindowConfigure`
`VentilationRoom`	`Building`, `Rooms`, `VentilationUnit`
`LightingSystems`	`Building`, `Rooms`
`HotwaterRoom`	`Building`, `Rooms`, `HotwaterSupplySystems`
`Elevators`	`Building`, `Rooms`

JSON Schema cannot fully express every cross-reference check. Before calculation, also use /validate or Builelib's validation function to confirm that referenced IDs exist.

Types, Required Fields, and Ranges¶

The schema uses the standard JSON Schema types string, number, boolean, null, object, and array. A type array such as ["string", "null"] permits either value. anyOf means that at least one of the listed conditions must be satisfied.

Fields listed in an object's required array are mandatory.
Numeric fields with minimum or maximum must fall within that range.
Strings with maxLength must not exceed that length.
A default is a reference value; normal JSON Schema validation does not automatically insert it.

Input Options¶

Input options come from two sources.

Type	Source
Fixed options	`enum` in `webproJsonSchema.json`
Database-derived options	`input_options.json` or `/options`

Options that depend on another value use a nested structure. Room uses, for example, are grouped by building use.

{
  "室用途": {
    "事務所等": [
      "事務室",
      "会議室"
    ]
  }
}

When building a form or input-completion feature, display values from input_options.json and validate the saved JSON against webproJsonSchema.json.

SpecialInputData¶

SpecialInputData stores optional input used by SP sheets and other Builelib-specific functions. It may include weather data, custom room-use conditions, custom heat-source characteristics, and time-series loads.

External programs should treat it as an optional object and interpret only known keys, because its detailed structure may change.

Recommended Validation Procedure¶

Confirm that the file can be parsed as JSON.
Validate its structure, types, required fields, and ranges with webproJsonSchema.json.
Check database-derived choices against input_options.json.
When necessary, call /validate for Builelib-specific validation.
Confirm the relationships between referenced IDs before calculation.

Note

Some extension values, including control methods added through SpecialInputData.flow_control, are injected into the schema dynamically by Builelib's validation process. For JSON containing extensions, use /validate or builelib.commons.inputdata_validation() in addition to the static schema.

Minimal Python validation example:

import json
from jsonschema import Draft7Validator

with open("webproJsonSchema.json", encoding="utf-8") as f:
    schema = json.load(f)

with open("input.json", encoding="utf-8") as f:
    inputdata = json.load(f)

validator = Draft7Validator(schema)
errors = sorted(validator.iter_errors(inputdata), key=lambda e: list(e.path))

if errors:
    for error in errors:
        path = " -> ".join(str(p) for p in error.absolute_path) or "root"
        print(f"{path}: {error.message}")
else:
    print("valid")

API Endpoints¶

Endpoint	Purpose
`GET /schema`	Returns `webproJsonSchema.json`
`GET /options`	Returns the available input options
`POST /validate`	Validates input JSON and returns a list of errors