Program JSON contract

Every program page offers the two consumer exports of release 2.4.0, read straight from the release by scripts.atlas_exports, as Program JSON 6.1.0:

• source: actual values only, as the source states them, including values the source implies as zero. Unknowns stay null with their reason.
• filled: actual values plus fillings and approved defaults, each filling recorded in metadata.resolutions with its rule and decision, and draw-only water heating. This is the version BEMGen consumes. Mixes are split into their members' loads; holiday rules are added to schedules that lack them (resolved-schedule-…).

The program page shows the source export under the download's own keys, then a Filled export section with every block the filled export changes, then the release record's fillings and the record values no export carries. ?version=source and ?version=filled hide the other export's blocks.

The major is 5; each data release added optional fields as a minor: 5.1.0 (DOE reference reconciliation: fenestration, source calendar, alternates, building services), 5.2.0 (IECC commercial: loads and schedules by climate, source zones), 5.3.0 (dwelling programs) and 5.4.0 (lighting controls, ADR 0044). A later minor's optional blocks render on the program page without a site change. IECC commercial, IECC residential and manufactured-housing programs export the source version only until their water heaters are stored; the coverage page counts them with the reason.

Contracts and schemas: consumer contracts of release 1.0.0, release 1.1.0, the release notes of each data release in docs/, and the schemas in schemas/. The exporter reads releases 2.0.0, 2.1.0, 2.2.0, 2.3.0, 2.4.0:

python -m scripts.atlas_exports --release 2.4.0 --program ID --version filled

Checksums

Each download names its release and the SHA-256 of the JSON file it saves. The file is the store's canonical JSON: keys sorted, no insignificant whitespace, UTF-8 without \u escapes, numbers as Python writes them, no trailing newline (json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(',', ':'))). The same JSON in any layout, such as the exporter's indented output, has the same canonical SHA-256:

python -m scripts.site_store program.json

Without JavaScript, Download saves the gzip file itself, named by the SHA-256 of its gzip bytes; decompressed, it is the canonical file. The site index guide describes the store.

Nulls and zeros

From release 2.3.0 (Program JSON 6.0.0, ADR 0054) a null never stands alone. Every load has a status: known (the source value, a source zero included), unknown (null, with its reason) or filled (a stored filling, with its rules and basis; filled version only). nulls gives every other null its meaning by JSON pointer: unknown (the source does not give it), none (known: there is none) or not_applicable (the field does not apply). A known 0 is a value: a source zero, or the accepted absence of an unknown load in the filled version (rule accepted_absence, ADR 0016, stored on the record). The filled version lists its zero loads in metadata.absent_demands.

From release 2.4.0, Program JSON 6.1.0 (ADR 0061) adds one optional field and nothing else: lighting_controls.unoccupied_lighting_cap, the source model's unoccupied lighting cap or, where the source has none, rule: null with its reason in nulls (lighting controls guide).

Hot water differs by family: DOE Ref and IECC programs carry it as a load, 0 where the source zone has no draw; a 90.1 program carries it only where openstudio-standards assigns a draw to its space type, and otherwise its folder's water.json says whether the space has no local draw, an unknown assignment or a share of a building draw. Conditioning differs too: IECC programs state it; 90.1 and DOE Ref programs state it where a filling sets it, and otherwise their setpoint schedules imply it.

The meanings, which the exporter applies (the first matching row wins):

JSON pointer (* one segment)	Meaning of null	Reason
/loads/*/value	unknown (or the record's)	The source does not give the magnitude.
/shared_services/*/loads/*/value	unknown (or the record's)	The source does not give the magnitude.
/loads/*/schedule_id	unknown	No schedule: the load's magnitude is unknown, or the source gives no schedule for it.
/shared_services/*/loads/*/schedule_id	unknown	No schedule: the load's magnitude is unknown, or the source gives no schedule for it.
/loads/*/heat_fractions/*	unknown	The source gives no heat fraction; the filled version applies the EnergyPlus default.
/shared_services/*/loads/*/heat_fractions/*	unknown	The source gives no heat fraction; the filled version applies the EnergyPlus default.
/loads/*/*	none	The source object leaves this field blank (no such input).
/shared_services/*/loads/*/*	none	The source object leaves this field blank (no such input).
/controls/people_radiant_fraction	unknown	The source gives no people radiant fraction; the filled version applies the EnergyPlus default (0.3).
/controls/people_sensible_fraction	unknown	The source gives no people sensible fraction; the filled version autocalculates it (EnergyPlus).
/controls/heating_enabled	unknown	The source states no conditioning; setpoint schedules, where given, imply it (the filled version resolves it).
/controls/cooling_enabled	unknown	The source states no conditioning; setpoint schedules, where given, imply it (the filled version resolves it).
/controls/*	unknown (or the record's)	The source gives no value for this control.
/default_policy_id	none	No default policy: the source version applies none.
/fenestration/wwr/*	not_applicable	No exterior wall faces this direction in the program's source zones.
/fenestration/roof	not_applicable	No exterior roof over the program's source zones.
/fenestration/value_by_climate/*/wwr/*	not_applicable	No exterior wall faces this direction in the program's source zones.
/fenestration/value_by_climate/*/roof	not_applicable	No exterior roof over the program's source zones.
/fenestration/variants/*/wwr/*	not_applicable	No exterior wall faces this direction in the dwelling's source zones.
/fenestration/variants/*/roof	not_applicable	No exterior roof over the dwelling's source zones.
/lighting_controls/daylighting	none	A source zero: the complete source model has no daylighting controls in these zones.
/lighting_controls/daylighting_by_climate/*	none	A source zero: the complete source model has no daylighting controls in these zones in that climate.
/lighting_controls/standards_rule/target_illuminance_setpoint_lux	none	openstudio-standards gives no target; its default of 375 lux applies (space_add_daylighting_controls).
/lighting_controls/unoccupied_lighting_cap/rule	none (or the record's)	A source zero: the complete source model has no unoccupied lighting cap in these zones.
/water_use_gains/*/sensible_fraction	unknown	The source gives no sensible fraction for the water use.
/water_use_gains/*/latent_fraction	unknown	The source gives no latent fraction for the water use.
/water_heating/*/service_id	none	A draw of the program itself, served by no shared building service.
/water_heating/*/draw/value	unknown (or the record's)	The source does not give the magnitude.
/water_heating/*/draw/heat_fractions/*	unknown	The source gives no heat fraction; the filled version applies the EnergyPlus default.
/water_heating/*/draw/*	none	The source object leaves this field blank (no such input).
/water_heating/*/*	none	The water heating has no such part.
/water_heating/*/stages/*/*	none	The water-heating stage has no such part.
/dwelling/climate	not_applicable	A code-prototype dwelling spans climates; entries that depend on climate carry applies_with.
/dwelling/vintage	not_applicable	A code-prototype dwelling has a code template, not a stock vintage.
/dwelling/*	unknown	The source dwelling records no value for this field.
/dwelling/*/*	unknown	The source dwelling records no value for this field.
/source_calendar/daylight_saving	none	The source model has no daylight saving period.