Use cases¶
A use case is a recipe: how to do one thing with this data. Each needs at least one of filter, dataset or then.
Write then so it reads well after the title. The card shows the first use case below as:
- compare markets (columns: rent_growth, sector): then use rent_growth within one sector; never across sectors. Pitfall: sectors differ in lease length.
filter is free text read by people and agents. No syntax is checked in v0.1; a filter language is not in the spec
yet.
Things not to do (hazards, do_not) are declared on the dataset: see Datasets.
Example¶
use_cases:
- id: compare-markets
use_case: compare markets
then: use rent_growth within one sector; never across sectors
pitfall: sectors differ in lease length
columns: [rent_growth, sector]
- use_case: office only
filter: "sector == 'office'"
- use_case: add market names
dataset: marketdata-example/Markets
Definitions¶
| Key | Type | Required | Priority | Check | Description |
|---|---|---|---|---|---|
use_cases[].use_case |
string | yes | Important | prose lint | The title. |
use_cases[].id |
string | no | Useful | error unless lower-case letters, digits and -, 2 to 63 characters; hint if absent |
Stable citation id. |
use_cases[].columns |
list of column names | no | Important | error if not declared on the dataset | Columns this recipe is about. |
use_cases[].filter |
string | one of filter, dataset, then |
Important | - | A row filter, as free text (no syntax is checked). |
use_cases[].dataset |
string | one of filter, dataset, then |
Important | error if a / form is not a valid id; a plain name must be a dataset |
Another dataset (or <project>/<Dataset>) to use. |
use_cases[].then |
string | one of filter, dataset, then |
Important | prose lint | What to do next. |
use_cases[].pitfall |
string | no | Important | prose lint | What goes wrong when the recipe is done the obvious way. |
use_cases[].why |
string | no | Important | prose lint | Why the recipe is right. |
use_cases[].source |
string | no | Useful | - | Where it was decided. |
use_cases[].probe |
string | no | Useful | error if absolute, contains : or .. |
Path to a committed script that re-checks the recipe. |