Kikai is the digital twin of every building we track — a queryable, standardized data layer where each real-world building is represented as structured, self-describing data that applications can reason over. The Kikai Standard is the data contract that implements that twin: it defines the shape, vocabulary, and semantics of every building record the Kikai API returns, so the twin looks the same to every consumer (the Akari UI, a customer's in-house tool, a third-party integrator, or another service in the Plentiful platform).
Concretely, the Standard is a building data contract based on schema.org/Building expressed as JSON-LD. Every building record returned by the Kikai API conforms to this contract.
Why a digital twin? A twin is useful because it separates what we know about a building from how any one product consumes it. The same twin can power a portfolio-level energy dashboard, a single-building deep-dive page, an ML prediction pipeline, and a customer's bespoke analytics — all without each consumer having to reinvent "what is a building" or re-query primary sources. Standardizing the twin's shape is what makes that reuse possible.
Why schema.org? Schema.org is a widely adopted vocabulary created by Google, Microsoft, Yahoo, and Yandex. Using it means our building data is interoperable with other systems that speak schema.org, search engines can understand our data, and developers familiar with the standard can work with Kikai immediately.
Why JSON-LD? JSON-LD (Linked Data) is a method of encoding Linked Data using JSON. It's the format recommended by schema.org. It looks like normal JSON but includes a @context that defines vocabulary prefixes, making the data self-describing.
{
"@context": {
"@vocab": "https://schema.org/",
"plentiful": "https://plentiful.ai/vocab/",
"ubid": "https://buildingid.pnnl.gov/",
"comstock": "https://www.nrel.gov/buildings/comstock.html#",
"plentiful:twinId": {
"@type": "@id"
},
"plentiful:dataRichness": {
"@type": "schema:Number"
},
"plentiful:comstockBuildingType": {
"@type": "@vocab"
},
"plentiful:ownerType": {
"@type": "@vocab"
},
"plentiful:mlPrediction": {
"@type": "schema:Boolean"
}
},
"$comment": "Kikai Standard v1 \u2014 canonical data contract. Schema.org JSON-LD compliant. This file is the schema definition; see kikai_standard.example.json for a concrete instance. Convention: $comment is used for field-level annotations (type info, enum docs, semantics). @comment is used intentionally for visual section dividers (e.g. '--- BUILDING CLASSIFICATION ---') \u2014 it is not a JSON-LD keyword and carries no semantic meaning; consumers should ignore @comment keys.",
"@type": "Building",
"identifier": [
{
"@type": "PropertyValue",
"propertyID": "ubid",
"name": "Unique Building Identifier (UBID)",
"$comment": "https://buildingid.pnnl.gov/ \u2014 canonical cross-system building ID"
},
{
"@type": "PropertyValue",
"propertyID": "plentiful_id",
"name": "Plentiful Building ID",
"$comment": "Internal UUID assigned by Plentiful platform"
}
],
"name": {
"@type": "Text",
"$comment": "Human-readable building name, typically derived from address"
},
"description": {
"@type": "Text",
"$comment": "Optional free-text description of the building"
},
"address": {
"@type": "PostalAddress",
"streetAddress": "Text",
"addressLocality": "Text",
"addressRegion": "Text \u2014 ISO 3166-2 subdivision code (e.g. PA, NY)",
"addressCountry": "Text \u2014 ISO 3166-1 alpha-2 (e.g. US)",
"postalCode": "Text",
"isBasedOn": {
"@type": "Thing",
"name": "Text \u2014 data source name (e.g. county_assessor, usps, osm)"
}
},
"mailingAddress": {
"@type": "PostalAddress",
"$comment": "Owner mailing address \u2014 may differ from building location address"
},
"geo": {
"@type": "GeoCoordinates",
"latitude": "Number \u2014 WGS 84 decimal degrees",
"longitude": "Number \u2014 WGS 84 decimal degrees",
"elevation": {
"@type": "QuantitativeValue",
"value": "Number",
"unitCode": "FOT",
"unitText": "feet above sea level"
}
},
"owner": {
"@type": "Organization",
"name": "Text",
"plentiful:ownerType": "Text \u2014 owner classification (e.g. REGULAR-ETAL, CORPORATE, GOVERNMENT)",
"isBasedOn": {
"@type": "Thing",
"name": "Text \u2014 data source (e.g. county_assessor)"
}
},
"floorSize": {
"@type": "QuantitativeValue",
"value": "Number",
"unitCode": "FTK",
"unitText": "square feet"
},
"yearBuilt": "Integer \u2014 four-digit year",
"additionalProperty": [
{
"@comment": "--- BUILDING CLASSIFICATION ---",
"@type": "PropertyValue",
"name": "buildingType",
"value": "Text \u2014 ComStock building type (e.g. MediumOffice, RetailStandalone, FullServiceRestaurant)"
},
{
"@type": "PropertyValue",
"name": "occupancyClass",
"$comment": "Enum \u2014 must be one of the values listed below. Classified from NSI `occtype` via the NORMATIVE crosswalk artifact schemas/crosswalks/occupancy/fema_hazus.json (edit the taxonomy there, only there); OccupancyClassEnum in app/models/twin.py is a derived copy pinned by test_occupancy_crosswalk. 'Other' is the complement node (NULL/unknown codes). Single Family and Multi-Family partition Residential exactly.",
"value": "Text \u2014 one of: Residential | Single Family | Multi-Family | Commercial | Industrial | Agriculture | Religion/Non-profit | Government | Education | Other"
},
{
"@type": "PropertyValue",
"name": "occupancySubClass",
"value": "Text \u2014 occupancy subclass (e.g. Religious, Single-family, Multi-family)"
},
{
"@type": "PropertyValue",
"name": "additionalType",
"value": "Text \u2014 supplemental type classification (e.g. RES1-1SNB)"
},
{
"@comment": "--- PHYSICAL CHARACTERISTICS ---",
"@type": "PropertyValue",
"name": "numberOfStories",
"value": {
"@type": "QuantitativeValue",
"value": "Number",
"unitText": "stories"
}
},
{
"@type": "PropertyValue",
"name": "foundationType",
"value": "Text \u2014 foundation classification code (e.g. S = slab, B = basement)"
},
{
"@type": "PropertyValue",
"name": "foundationHeight",
"value": {
"@type": "QuantitativeValue",
"value": "Number",
"unitCode": "FOT",
"unitText": "feet"
}
},
{
"@type": "PropertyValue",
"name": "groundElevation",
"value": {
"@type": "QuantitativeValue",
"value": "Number",
"unitCode": "FOT",
"unitText": "feet above sea level"
}
},
{
"@type": "PropertyValue",
"name": "conditionedArea",
"value": {
"@type": "QuantitativeValue",
"value": "Number",
"unitCode": "FTK",
"unitText": "square feet"
}
},
{
"@type": "PropertyValue",
"name": "structureValue",
"value": {
"@type": "MonetaryAmount",
"currency": "USD",
"value": "Number \u2014 estimated replacement value"
}
},
{
"@type": "PropertyValue",
"name": "dataRichness",
"value": "Number 0\u20131 \u2014 completeness score for this building record"
},
{
"@comment": "--- BUILDING UPGRADES / PHYSICAL CHARACTERISTICS ---",
"@type": "PropertyValue",
"name": "airtightness",
"value": {
"@type": "QuantitativeValue",
"value": "Number",
"unitText": "m\u00b3/m\u00b2/hr",
"$comment": "Air leakage rate. source property indicates data provenance."
},
"measurementTechnique": "Text (e.g. measured, modeled, randomly_generated)"
},
{
"@type": "PropertyValue",
"name": "primaryHeatingFuel",
"$comment": "ComStock-derived enum \u2014 common values listed; see ComStock docs for full set.",
"value": "Text \u2014 one of: NaturalGas | Electricity | DistrictHeating | FuelOil | Propane | Coal | OtherFuel",
"measurementTechnique": "Text"
},
{
"@type": "PropertyValue",
"name": "hvacCategory",
"$comment": "ComStock-derived enum \u2014 common values listed; see ComStock docs for full set.",
"value": "Text \u2014 one of: PTAC | SmallPackagedUnit | LargePackagedUnit | SplitSystem | WaterSourceHeatPump | GroundSourceHeatPump | DOAS | CentralAirHandler",
"measurementTechnique": "Text"
},
{
"@type": "PropertyValue",
"name": "hvacCoolerType",
"$comment": "ComStock-derived enum \u2014 common values listed; see ComStock docs for full set.",
"value": "Text \u2014 one of: ASHP | DX | ChilledWater | GSHP | None",
"measurementTechnique": "Text"
},
{
"@type": "PropertyValue",
"name": "hvacHeaterType",
"$comment": "ComStock-derived enum \u2014 common values listed; see ComStock docs for full set.",
"value": "Text \u2014 one of: FurnaceGas | HeatPump | District | ElectricResistance | HotWaterBoiler | SteamBoiler | GSHP | None",
"measurementTechnique": "Text"
},
{
"@type": "PropertyValue",
"name": "buildingVintage",
"$comment": "Enum \u2014 must be one of the values listed below. Closed ComStock era classification.",
"value": "Text \u2014 one of: Before 1946 | 1946-1980 | 1980-2004 | 2004-Present",
"measurementTechnique": "Text"
},
{
"@type": "PropertyValue",
"name": "wallConstructionType",
"$comment": "ComStock-derived enum \u2014 common values listed; see ComStock docs for full set.",
"value": "Text \u2014 one of: Mass | WoodFrame | SteelFrame | ICF | SpandrelGlass",
"measurementTechnique": "Text"
},
{
"@type": "PropertyValue",
"name": "windowType",
"value": "Text \u2014 glazing description (e.g. Double - No LowE - Clear - Aluminum)",
"measurementTechnique": "Text"
},
{
"@comment": "--- UTILITY INFORMATION ---",
"@type": "PropertyValue",
"name": "servingElectricUtility",
"value": "Text \u2014 utility company name"
},
{
"@type": "PropertyValue",
"name": "servingElectricUtilityId",
"value": "Text \u2014 EIA utility ID"
},
{
"@type": "PropertyValue",
"name": "stateKwhRate",
"value": {
"@type": "UnitPriceSpecification",
"price": "Number",
"priceCurrency": "USD",
"unitText": "per kWh"
}
},
{
"@comment": "--- ENERGY USE PREDICTIONS ---",
"@type": "PropertyValue",
"name": "energyPredictions",
"$comment": "Array of ML-predicted energy use scenarios. First element is always Baseline.",
"value": [
{
"@type": "PropertyValue",
"name": "scenarioName",
"$comment": "e.g. Baseline, HeatPump, RoofInsulation, WallInsulation, LEDLighting",
"additionalProperty": [
{
"@type": "PropertyValue",
"name": "out.site_energy.total.energy_consumption..kwh",
"value": {
"@type": "QuantitativeValue",
"value": "Number",
"unitCode": "KWH"
},
"plentiful:mlPrediction": true
},
{
"@type": "PropertyValue",
"name": "out.electricity.total.energy_consumption..kwh",
"value": {
"@type": "QuantitativeValue",
"value": "Number",
"unitCode": "KWH"
},
"plentiful:mlPrediction": true
},
{
"@type": "PropertyValue",
"name": "out.natural_gas.total.energy_consumption..kwh",
"value": {
"@type": "QuantitativeValue",
"value": "Number",
"unitCode": "KWH"
},
"plentiful:mlPrediction": true
}
]
}
]
},
{
"@comment": "--- OWNER ENRICHMENT ---",
"@type": "PropertyValue",
"name": "ownerEnrichment",
"$comment": "Apollo/third-party contact enrichment for the building owner",
"additionalProperty": [
{
"@type": "PropertyValue",
"name": "lastEnriched",
"value": "DateTime | null"
},
{
"@type": "PropertyValue",
"name": "businessName",
"value": "Text | null"
},
{
"@type": "PropertyValue",
"name": "websiteUrl",
"value": "URL | null"
},
{
"@type": "PropertyValue",
"name": "organizationRevenue",
"value": "Number | null"
},
{
"@type": "PropertyValue",
"name": "contactFirstName",
"value": "Text | null"
},
{
"@type": "PropertyValue",
"name": "contactLastName",
"value": "Text | null"
},
{
"@type": "PropertyValue",
"name": "contactTitle",
"value": "Text | null"
},
{
"@type": "PropertyValue",
"name": "contactEmail",
"value": "Text | null"
},
{
"@type": "PropertyValue",
"name": "contactSeniority",
"value": "Text | null"
}
]
}
],
"permit": [
{
"@type": "Permit",
"identifier": "Text \u2014 permit number",
"name": "Text \u2014 short description of permitted work",
"description": "Text \u2014 full scope of work",
"validFrom": "Date \u2014 permit issue date (ISO 8601)",
"issuedBy": {
"@type": "Organization",
"name": "Text \u2014 issuing authority or contractor"
},
"additionalProperty": [
{
"@type": "PropertyValue",
"name": "permitType",
"value": "Text (e.g. Building, Electrical, Demolition, Plumbing)"
},
{
"@type": "PropertyValue",
"name": "workType",
"value": "Text (e.g. NEW CONSTRUCTION, ADDITION, COMPLETE DEMOLITION)"
},
{
"@type": "PropertyValue",
"name": "commercialOrResidential",
"value": "Text \u2014 Commercial | Residential"
},
{
"@type": "PropertyValue",
"name": "totalProjectValue",
"value": {
"@type": "MonetaryAmount",
"currency": "USD",
"value": "Number"
}
},
{
"@type": "PropertyValue",
"name": "status",
"$comment": "Enum \u2014 must be one of the values listed below.",
"value": "Text \u2014 one of: Active | Completed | Expired | Voided"
},
{
"@type": "PropertyValue",
"name": "ownerName",
"value": "Text"
},
{
"@type": "PropertyValue",
"name": "contractorName",
"value": "Text"
}
]
}
],
"sameAs": [
"URL \u2014 links to the same building in other authoritative databases"
],
"potentialAction": [
{
"@type": "Action",
"$comment": "Placeholder for future upgrade recommendation actions"
}
]
}@contextEvery building response includes a context block:
{
"@context": {
"@vocab": "https://schema.org/",
"plentiful": "https://plentiful.ai/vocab/",
"ubid": "https://buildingid.pnnl.gov/",
"comstock": "https://www.nrel.gov/buildings/comstock.html#"
}
}
| Prefix | Source | Purpose |
|---|---|---|
@vocab (schema.org) |
schema.org | Base vocabulary — address, geo, owner, yearBuilt, etc. |
plentiful |
Plentiful.ai | Custom extensions — ownerType, mlPrediction, dataRichness |
ubid |
PNNL | Unique Building Identifier — cross-system canonical building ID |
comstock |
NREL ComStock | Building type classifications derived from the DOE ComStock model |
These are standard schema.org properties on every building:
| Field | Type | Description |
|---|---|---|
@type |
"Building" |
Always "Building" |
@id |
URL | Canonical identifier (e.g. https://plentiful.ai/buildings/{uuid}) |
name |
Text | Human-readable name, typically the full address |
address |
PostalAddress | Physical street address with city, state, ZIP, country |
mailingAddress |
PostalAddress | Owner's mailing address (may differ from building location) |
geo |
GeoCoordinates | WGS 84 latitude, longitude, and optional elevation in feet |
owner |
Organization | Property owner name and classification |
floorSize |
QuantitativeValue | Total floor area in square feet (unitCode: "FTK") |
yearBuilt |
Integer | Four-digit construction year |
identifier |
PropertyValue[] | Array of IDs — UBID and Plentiful UUID |
permit |
Permit[] | Construction permit history |
sameAs |
URL[] | Links to this building in other databases |
The additionalProperty array carries extended building data as named PropertyValue entries. Each has a name and a value (which may be a scalar, object, or array).
| Property Name | Type | Description |
|---|---|---|
buildingType |
Text | ComStock building type (e.g. "MediumOffice", "RetailStandalone") |
occupancyClass |
Enum | Broad occupancy category. One of: Assembly, Commercial, Education, Government, Industrial, Mixed Use, Residential, Agriculture, Utility and Misc., Unclassified |
occupancySubClass |
Text | Narrower occupancy type (e.g. "Religious", "Single-family") |
additionalType |
Text | Supplemental classification code (e.g. "RES1-1SNB") |
| Property Name | Type | Description |
|---|---|---|
numberOfStories |
QuantitativeValue | Number of above-grade stories |
foundationType |
Text | Foundation classification ("S" = slab, "B" = basement) |
foundationHeight |
QuantitativeValue | Foundation height in feet |
groundElevation |
QuantitativeValue | Ground elevation in feet above sea level |
conditionedArea |
QuantitativeValue | Conditioned floor area in square feet |
structureValue |
MonetaryAmount | Estimated replacement value in USD |
dataRichness |
Number | Completeness score 0–1 for this building record |
These properties describe the building's mechanical systems. Each includes a measurementTechnique field indicating data provenance ("measured", "modeled", or "randomly_generated").
| Property Name | Enum Values | Description |
|---|---|---|
primaryHeatingFuel |
NaturalGas, Electricity, DistrictHeating, FuelOil, Propane, Coal, OtherFuel |
Primary heating fuel source |
hvacCategory |
PTAC, SmallPackagedUnit, LargePackagedUnit, SplitSystem, WaterSourceHeatPump, GroundSourceHeatPump, DOAS, CentralAirHandler |
HVAC system category |
hvacCoolerType |
ASHP, DX, ChilledWater, GSHP, None |
Cooling system type |
hvacHeaterType |
FurnaceGas, HeatPump, District, ElectricResistance, HotWaterBoiler, SteamBoiler, GSHP, None |
Heating system type |
buildingVintage |
Before 1946, 1946-1980, 1980-2004, 2004-Present |
Era classification |
wallConstructionType |
Mass, WoodFrame, SteelFrame, ICF, SpandrelGlass |
Wall assembly type |
windowType |
Free text | Glazing description (e.g. "Double - No LowE - Clear - Aluminum") |
airtightness |
QuantitativeValue | Air leakage rate in m³/m²/hr |
| Property Name | Type | Description |
|---|---|---|
servingElectricUtility |
Text | Utility company name |
servingElectricUtilityId |
Text | EIA utility identifier |
stateKwhRate |
UnitPriceSpecification | Average electricity rate in USD per kWh |
The energyPredictions property contains ML-predicted energy consumption scenarios. The first element is always the baseline; subsequent elements represent upgrade scenarios (e.g. heat pump, LED lighting).
{
"name": "energyPredictions",
"value": [
{
"name": "Baseline",
"additionalProperty": [
{ "name": "out.site_energy.total.energy_consumption..kwh", "plentiful:mlPrediction": true, "value": { "value": 49889, "unitCode": "KWH" } },
{ "name": "out.electricity.total.energy_consumption..kwh", "plentiful:mlPrediction": true, "value": { "value": 37112, "unitCode": "KWH" } },
{ "name": "out.natural_gas.total.energy_consumption..kwh", "plentiful:mlPrediction": true, "value": { "value": 0.06, "unitCode": "KWH" } }
]
},
{ "name": "Heat Pump", "additionalProperty": [ ... ] },
{ "name": "LED Lighting", "additionalProperty": [ ... ] }
]
}
The plentiful:mlPrediction: true flag indicates these values are model-generated, not observed.
The ownerEnrichment property contains third-party contact data for the building's owner:
| Nested Property | Type | Description |
|---|---|---|
lastEnriched |
DateTime | When enrichment was last updated |
businessName |
Text | Business name from enrichment provider |
websiteUrl |
URL | Owner's website |
organizationRevenue |
Number | Estimated annual revenue (USD) |
contactFirstName |
Text | Primary contact first name |
contactLastName |
Text | Primary contact last name |
contactTitle |
Text | Contact job title |
contactEmail |
Text | Contact email address |
contactSeniority |
Text | Contact seniority level |
The canonical JSON schema definition is available at:
GET /api/v1/standards/schema
This returns the raw kikai_standard.json file — the authoritative schema definition with field-level annotations, enum values, and type information.
A concrete example of a building conforming to this standard is available at:
GET /api/v1/standards/example