Why¶
Five ways an agent misreads data that a person reads fine, and the few lines of YAML that prevent each. Each example has four parts: the situation, what the agent says, the declaration, and what changes.
1. A unit that looks like another unit¶
The situation. The dataset Rents has a column rent_growth. The vendor file's header says "Rent growth (%)".
The values look like 0.012.
What the agent says.
"Office rents in Market A grew 0.012% last quarter, essentially flat."
The values are fractions. 0.012 is 1.2%, a strong quarter.
The declaration.
columns:
rent_growth:
description: quarter-on-quarter rent growth
unit: decimal
decimal means a plain fraction: 0.012 is 1.2%. It is a short name for the UCUM unit 1.
What changes. The agent's card lists rent_growth with the unit decimal. It reports "rents grew
1.2%". A checker also rejects a unit that is not a valid unit.
2. A release that is not the latest¶
The situation. You load Rents. The vendor sent a newer file last week; nobody has rebuilt the table. Nothing in
the table says which release it holds.
What the agent says.
"Latest rents, as of today: ..."
It is quoting last quarter's release.
The declaration.
dates_asof:
vendor_a:
constant: "2026-06-30"
cadence: quarterly
This says: the vendor_a data in this table is the release with the as-of date 30 June
2026, and the vendor releases quarterly. If your data has the date in a column, write column: asof_date instead of
constant. See As-of dates.
What changes. The card shows "vendor_a 2026-06-30 (constant) (quarterly)". The agent says "rents as of the 2026-06-30 release of vendor_a", and a reader can see it is one quarter old. Which release to use stays the data owner's choice. Nothing warns yet that a newer release should exist; the as-of date is shown, not judged.
3. A join that double-counts¶
The situation. Rents has one row per market, sector and quarter. A second dataset, Leases, has many rows per
market. An agent joins them on market_id and sums rent.
What the agent says.
"Total asking rent across markets rose 40% after adding lease data."
Each rent row was repeated once per lease. The total is inflated.
The declaration. Declare the grain (the columns that identify one row) of each dataset:
datasets:
Rents:
grain: [market_id, sector, period_yq]
Markets:
grain: [market_id]
Leases:
grain: [lease_id]
What changes. Each card says "Grain (D): one row per market_id x sector x period_yq". With both grains in view,
an agent can tell that Rents to Markets on market_id is many-to-one and safe, and that market_id does not
identify a row of Leases. Most joins need nothing more than the grain.
4. A key that looks joinable but is not¶
The situation. Rents and Markets both have a market name column. Some markets are spelled two ways.
What the agent says.
"Rents by market name: 52 markets matched."
Three markets silently dropped out of the join.
The declaration. Where the grain cannot tell, declare a relationship:
relationships:
- name: rents_to_markets
from: Rents
to: Markets
from_columns: [market_id]
to_columns: [market_id]
ai_context: join on market_id, never on market names
What changes. The card's Joins section shows "Rents.market_id -> Markets.market_id (many to one): join on market_id, never on market names". The agent joins on the code. See Relationships.
5. A definition that changed¶
The situation. Since 2026Q2 the vendor counts flex space as office. An agent compares office rents in 2025 with 2027.
What the agent says.
"Office rents jumped in 2026Q2."
The jump is the definition change, not the market.
The declaration. A dated fact:
facts:
- id: office-incl-flex
statement: "office includes flex space from 2026Q2: compare office within one side of 2026Q2 only"
as_of: 2026-10-31
severity: caution
status: reviewed
reviewed_by: data-team
What changes. The card lists the fact under Facts, with its severity and date. The agent compares office within
one side of 2026Q2, or says why it did not. The fact has an id, so a memo can cite
marketdata-example/Rents/fact:office-incl-flex. A fact answers two separate questions, how much it matters and how
sure we are: see Facts.
All examples are synthetic: project marketdata-example, datasets Rents, Markets and Leases.