# The Indoor Temperature Schema (v0.1)

*A WhatTemp open specification — the canonical way to publish the indoor temperature of a place.*

---

## Why this exists

Indoor temperature is the most-felt, least-published fact about a venue. Today every thermostat
vendor speaks its own dialect (Nest, Ecobee, Honeywell, SmartThings) and no neutral format exists
for *publishing* a reading to the open web. This schema is that format.

It is deliberately small, attributable, and consumable as both plain JSON and JSON-LD (so it can ride
alongside existing `schema.org/Place` markup). The goal: a search engine, map, or listing can ingest
**one object** and render "Indoor temperature: 64°F — bring a sweater," with provenance, from any source.

**Owning this standard — and the verified dataset that fills it — is the company.** The app is the
demand-side wedge; this schema and the cross-vendor pipeline behind it are the saleable IP.

## The design in one breath

A reading is **not just a number**. It carries:

| Field | Why it's in the standard |
|---|---|
| `temperature` | The raw value + unit (`FAH`/`CEL`, UN/CEFACT codes). |
| `comfort` | The *interpretation* — a normalized `band` and a plain-language `verdict`. This is the product. |
| `source` | `device` \| `crowd` \| `estimate`. The trust backbone. |
| `confidence` | 0–100, so a consumer can decide whether to display it. |
| `provenance` | Attribution + `verified` + license — non-negotiable for Google/Maps to surface it. |
| `zones` | Optional per-zone readings (e.g. individual auditoriums). |

## Files

- [`indoor-temperature.schema.json`](indoor-temperature.schema.json) — JSON Schema (draft 2020-12). The normative contract.
- [`example-reading.json`](example-reading.json) — a conformant reading.

## Reference implementation (live)

The WhatTemp backend serves conformant readings today:

```
GET /api/v1/schema            → this JSON Schema
GET /api/v1/readings          → every published place as an IndoorTemperatureReading[]
GET /api/v1/readings/:id      → one place (e.g. /api/v1/readings/o-cinema)
```

Every object returned validates against the schema above. That is the proof the standard is real:
the same pipeline that powers the consumer app emits the public interchange format.

## How a partner would use it

1. A venue connects a thermostat (read-only, `thermostat.read`) and toggles **public** — once.
2. WhatTemp normalizes the vendor's reading into an `IndoorTemperatureReading`.
3. A search engine / map fetches `GET /api/v1/readings/:id`, validates, and renders the
   `comfort.verdict` with `provenance.attribution`.
4. The venue's listing now shows live indoor comfort everywhere — not just in the WhatTemp app.

## Comfort bands (normative)

Bands are unit-independent. Reference thresholds in °F:

| Band | °F (≤) | Default verdict |
|---|---|---|
| `cold` | 60 | Bundle up — it's cold inside |
| `cool` | 67 | Bring a sweater |
| `comfortable` | 72 | You're good as you are |
| `warm` | 78 | Light layers, max |
| `hot` | — | Leave the jacket home |

## Versioning

`v0.1` is a draft for partner review. Breaking changes bump the minor version and the `$id` path.
The `@context` and `$id` are namespaced under `schema.whattemp.org` — the standard is ours to steward.

## License

The schema is published openly to drive adoption. The **data** that fills it (the verified, scored,
cross-vendor readings) is licensed — see `provenance.license`. Open standard, proprietary dataset.