feat!: Align data dictionaries with the current data-dict spec (#316)

pkg-py/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Breaking changes
+
+* `DataDict` now follows the current [data-dict spec](https://data-dict.tidyverse.org/spec.html): `tables` is a list of tables each with a `name` field (previously a mapping of name to definition), column `range` is a two-element `[min, max]` list, `values` may be a value-to-label map, and `constraints` may include assertion objects. Files written in the older mapping format, or with a `$version` that is invalid or predates the first spec version, fail with a descriptive error explaining how to update. Files declaring a `$version` newer than the spec version querychat understands are still read on a best-effort basis (unknown fields are ignored), with a warning. (#316)
+
 ### New features
 
 * **Faster iterative visualization, and support for layer-level data sources.** Visualization queries now execute as a whole through `ggsql.CachingReader`: the underlying SQL runs against your data source once and the result is memoized for the chat session, so re-rendering a chart with a different encoding no longer re-queries the source (a win for remote databases especially). Visualization layers can also draw from other relations in the query — e.g. raw points from the final `SELECT` with a summary line from a CTE — via `DRAW ... MAPPING ... FROM <source>`. Caching can be tuned or disabled with the `GGSQL_CACHE_TTL`, `GGSQL_CACHE_MAX_BYTES`, and `GGSQL_CACHE_DISABLED` environment variables. (#321)

pkg-py/docs/context.qmd

@@ -30,13 +30,13 @@ qc.add_table(customers, "customers")
 
 ### Format
 
-A data dictionary has three top-level sections: `tables`, `relationships`, and `glossary`.
+The file format is defined by the [data-dict spec](https://data-dict.tidyverse.org/spec.html). A data dictionary has three top-level sections: `tables`, `relationships`, and `glossary`. The optional `$version` field declares the spec version the file conforms to. A `$version` that is invalid or predates the first spec version fails with a descriptive error; a file declaring a version newer than querychat understands is still read on a best-effort basis (unknown fields are ignored), with a warning.
 
 ```{.yaml filename="data-dict.yaml"}
-version: "0.2.0"
+$version: "0.1.0"
 
 tables:
-  orders:
+  - name: orders
     description: One row per customer order.
     columns:
       - name: order_id
@@ -55,7 +55,7 @@ tables:
         values: [pending, shipped, delivered, cancelled]
         description: Current order status.
 
-  customers:
+  - name: customers
     description: One row per customer.
     columns:
       - name: id
@@ -81,15 +81,16 @@ glossary:
 
 #### Tables
 
-Each entry under `tables` describes one table. The key must match the table name you pass to `QueryChat` or `.add_table()`.
+Each entry under `tables` describes one table. Its `name` must match the table name you pass to `QueryChat` or `.add_table()`.
 
 - **`description`**: What this table represents (one sentence is usually enough).
 - **`columns`**: A list of column annotations. Each column can have:
   - `name`: Column name (must match the actual column)
   - `type`: Semantic type hint — `string`, `number`, `number(id)`, `number(quantity)`, `date`, `enum`
-  - `constraints`: Optional list — `primary_key`, `foreign_key`
+  - `constraints`: Optional list — barewords like `primary_key`/`foreign_key`, or assertion objects (`assert` with an optional `language` and `description`)
   - `description`: What this column means in plain English
-  - `values`: For `enum` columns, the list of possible values
+  - `values`: For `enum` columns, the possible values — a list, or a value-to-label map (e.g. `{M: Male, F: Female}`)
+  - `range`: Optional `[min, max]` bounds. Either end may be left open with the `-.inf`/`.inf` sentinels (or `null`) — if you leave a bound open, describe the range in prose in the column's `description`. Replaces live min/max queries for the column
 
 Columns listed in the data dictionary are excluded from the auto-generated schema (since your description supersedes the auto-detected metadata). Columns not listed are still auto-detected as usual.
 

pkg-py/examples/11-multi-table-nutrition/nutrition-data-dict.yaml

@@ -1,7 +1,7 @@
-version: "0.2.0"
+$version: "0.1.0"
 
 tables:
-  foods:
+  - name: foods
     description: >
       One row per USDA Foundation Food item. Nutrient values are not stored here —
       see food_nutrients. All nutrient amounts in food_nutrients are per 100g of the food.
@@ -21,7 +21,7 @@ tables:
         type: date
         description: Date the food record was published by USDA.
 
-  food_categories:
+  - name: food_categories
     description: Lookup table of USDA food categories. One row per category.
     columns:
       - name: id
@@ -35,7 +35,7 @@ tables:
         type: string
         description: Human-readable category name (e.g., "Vegetables and Vegetable Products").
 
-  nutrients:
+  - name: nutrients
     description: >
       Registry of the 12 key nutritional compounds tracked in this dataset.
       One row per nutrient type. See the glossary for the full list of nutrient IDs.
@@ -54,7 +54,7 @@ tables:
         values: [G, KCAL, MG]
         description: Unit of measurement. G = grams, KCAL = kilocalories, MG = milligrams.
 
-  food_nutrients:
+  - name: food_nutrients
     description: >
       Nutrient content per 100g of food. One row per food–nutrient combination.
       Only the 12 key nutrients are included (see nutrients table and glossary).
@@ -76,7 +76,7 @@ tables:
           nutrients.unit_name. May be null if the nutrient was not measured
           for this food.
 
-  food_portions:
+  - name: food_portions
     description: >
       Common serving sizes for foods. One row per portion definition.
       A single food may have multiple portions (e.g., "1 cup" and "1 oz").
@@ -107,7 +107,7 @@ tables:
           Optional preparation note for the portion (e.g., "chopped", "drained",
           "cooked"). Null when no modifier applies.
 
-  measure_units:
+  - name: measure_units
     description: >
       Lookup table of measurement unit names used in food_portions.
       Only units that appear in food_portions are included (~32 of the 123 total).