# Data folders and live data reference

> Data folders, their schemas and kinds of value, and live data such as the weather.

## Data folders and their schemas

- **Every data folder has a schema:** a file that lists the fields its records have, and the kind of value each holds. The schema for `_data/news/` is `_data/news.schema.yml`.
- **`ws preview` writes the schema** from the first record you add to a new folder. Open it to check the kinds `ws` chose, mark a field `optional` if needed, and commit it with the record. `ws push` sends only committed files, so it does not write the schema.
- **`ws push` refuses a record that does not match** its folder's schema, and names the record, the field and what was expected. To add a field, add it to the schema first.
- **Kinds of value:** `text`, `markdown`, `date`, `number`, `price`, `link`, `image`, `slug` (lowercase letters, numbers and hyphens) and `yes-no`.
- **`translate: true`** marks a field that is written in each language. `ws` sets it on `text`, `markdown` and `slug` fields; dates, numbers, prices, links and images are shared by every language.

```yaml
# _data/news.schema.yml
title: { kind: text, translate: true }
date:  { kind: date }
slug:  { kind: slug, translate: true }
body:  { kind: markdown, translate: true }
photo: { kind: image, optional: true }
```

A single data file, such as `_data/hours.yml`, has no schema.


## Live data

At launch there is one source of live data, the weather. Others, such as an owner's Google reviews or real estate listings, are added later, each after its service's terms are read.

| Source | Needs | Rules from the service |
|---|---|---|
| `weather` | No account, only the town and its province, given to `ws sources connect`, such as `"Mahone Bay NS"`. The platform fetches it at least every 10 minutes, and keeps showing the last weather for 3 hours when the service is down. | Shows "Data Source: Environment and Climate Change Canada" (`live.credit`). |

- **The weather comes from Environment and Climate Change Canada's City Page Weather service,** at `api.weather.gc.ca`. It is free, needs no key, and covers 844 places in Canada, in English and French. `ws sources connect` finds the town in Canada's place names by its name and province, then picks the place nearest it, in any province. When several places far apart share the name in that province, it lists them by their nearest weather and asks which, such as `ws sources connect weather "L'Anse-au-Loup NL near Grand Bank"`. `near` takes one of the weather places listed and connects to exactly that place; anything else lists them again. Environment Canada marks this service as experimental, so the platform falls back to the same data on its file server, `dd.weather.gc.ca`.
- **`live.item` is the current weather,** with `temperature` (in °C), `wind` (such as "W 14 km/h"), `humidity` (in %) and `updated`, the time Environment Canada measured it.
- **`live.items` is the forecast,** up to 13 periods such as "Tonight" and "Sunday", each with `name`, `summary` (such as "Mainly cloudy"), `temperature` and `text`, the full forecast for that period.
- **On a page in French,** the names, summaries, wind directions and credit line are in French.
- **The platform's server fills in the part between the `{% live %}` tags with the newest records, and puts it into the page before sending it.** The browser gets one finished page, with no script.
- **When the source cannot be reached,** the page shows the last records the platform got, for up to 3 hours. After that it shows the part after `{% fallback %}`. The rest of the page is served as usual.
- **Previews and changes waiting for approval** read the same source as the published site.

```html
{% live 'weather' %}
  <p>Now: {{ live.item.temperature }} °C, wind {{ live.item.wind }}.</p>
  <ul>
    {% for period in live.items limit: 4 %}
      <li>{{ period.name }}: {{ period.summary }}</li>
    {% endfor %}
  </ul>
  <p><small>{{ live.credit }}</small></p>
{% fallback %}
  <p><a href="https://weather.gc.ca">Weather for Saltmere</a></p>
{% endlive %}
```

