Data Dictionaries, Schema Docs and Metric Definitions as AI Grounding Data

Why documentation is a training signal, not a delivery appendix

Schema documentation is the evidence that lets a model resolve ambiguity that DDL alone cannot. BIRD was built because earlier benchmarks focused on schema with few rows of content; it pairs questions with external-knowledge evidence and stresses dirty values and value comprehension, and at release ChatGPT reached 40.08% execution accuracy against 92.96% for humans [1]. A secondary write-up reports a large accuracy drop when the curated evidence is removed; treat its figures as secondhand, but the direction matches the paper [5].

Enterprise work raises the bar further. Spider 2.0, accepted at ICLR 2025, frames tasks that require searching database metadata, SQL dialect documentation and project codebases, so reading documentation is part of the task itself [2]. Its 632 problems sit on real application databases rather than toy schemas [3].

This page covers documentation as the signal. If you need question and gold-SQL pairs, see text-to-SQL training data from real enterprise schemas; for the cards that describe a delivered dataset, see dataset cards for licensed enterprise data.

What counts as schema documentation for an LLM

Useful grounding data spans five artifact families, and each fails in a different way. Ask for all of them, then score each one separately.

• Physical metadata. INFORMATION_SCHEMA exports, COMMENT ON COLUMN text in Postgres, column descriptions in Snowflake or BigQuery, primary and foreign keys (declared and undeclared), and partitioning or clustering keys. Failure mode: comments that are empty on most columns or simply restate the column name.
• Code and lookup tables. Enumerations such as status_cd = 'X' meaning "cancelled after shipment", SAP-style domain values, ICD or NAICS crosswalks, and legacy flags that changed meaning after a migration. This is where BIRD-style "value comprehension" lives [1].
• Business glossary. Terms like "active customer", "churned account" or "booked vs. billed" mapped to tables, filters and owners, typically exported from a catalog tool. See the data catalog definition for how these systems structure terms.
• Metric definitions. Semantic-layer files: dbt semantic_models and metrics YAML (MetricFlow), LookML measure and dimension blocks, Cube schemas, or a finance team's metric spec. These encode grain, time spine, filters and fan-out rules a model otherwise guesses wrong.
• Report and analyst artifacts. Report specs, dashboard SQL, dbt model SQL with docs blocks, Jira tickets explaining a column change, and "known caveats" wiki pages. Pair these with real query history to show how columns are used in practice; see schema linking and schema retrieval data.

How to judge coverage, freshness and contradiction

Real documentation is incomplete and stale, and that is a feature you should measure rather than a defect you should hide. A grounding model has to learn when a description is wrong, so request versioned documentation alongside the schema history it describes.

Score each candidate dataset on four measurable properties:

1. Coverage: share of columns with a non-trivial description, share of coded columns with a value map, share of tables with a declared grain.
2. Freshness: last-modified dates on comments and YAML versus the last DDL change on the same object; a description older than a column rename is a known-wrong label.
3. Contradiction rate: cases where the glossary, the semantic layer and dashboard SQL compute the same metric differently. These are high-value evaluation items.
4. Linkability: whether each glossary term and metric resolves to concrete table and column identifiers, not just prose.

NVIDIA's NeMo Data Designer text-to-SQL pipeline injects distractor tables and columns so models learn to ignore irrelevant schema, which signals that the design of schema context matters as much as its volume [4]. Real enterprise documentation provides natural distractors: deprecated tables, _bak copies and half-documented staging schemas. Keep them, labeled, rather than letting a supplier clean them out. Run the structural checks in validation checks for structured dataset deliveries on the paired database.

Ask each supplier for a short sample before scoring at scale: one subject area, such as orders or billing, with its tables, comments, code tables, glossary terms and metric YAML exported together. Compute the four scores on that sample, then spot-check ten descriptions against the actual data with simple profiling queries (distinct values, null rates, date ranges). A description that says "always populated" on a column that is 40% null is exactly the kind of documented-versus-actual gap your copilot will meet in production, so label it rather than fix it.

Request template for documentation-grounded text-to-SQL data

The fastest way to get comparable offers is to specify the artifacts, the pairing and the scoring up front.

Illustrative example: invented to show structure; it does not describe an available dataset.

A single delivered record might look like this:

{
  "object": "analytics.fct_orders.net_revenue_usd",
  "description": "Order revenue after returns and discounts, excluding tax and shipping.",
  "doc_last_modified": "2024-03-11",
  "ddl_last_modified": "2025-08-02",
  "value_map": null,
  "metric_ref": "metrics/net_revenue.yml",
  "glossary_terms": ["Net revenue", "Booked revenue"],
  "conflicts": ["dashboard 'Weekly Sales' includes shipping"],
  "reviewer_flag": "possibly_stale"
}

Rights, confidentiality and privacy in metadata

Metric definitions and glossaries can expose confidential business logic, so include them explicitly in rights review rather than treating metadata as harmless. A churn definition, a pricing-tier enumeration or a commission formula may be more sensitive to the supplier than the rows themselves.

Check three things before contracting. First, whether the documentation was written by employees, contractors or a vendor, since authorship affects who can license it. Second, whether comments and glossary entries contain personal data, such as an analyst's name in a caveat or a customer named in a code-table description; see indirect identifiers in business text. Third, whether your license covers retrieval-time grounding, weight training or both; grounding license vs. training license explains the difference.

As of October 2026, if the result trains a generative AI system made available to Californians, AB 2013 requires the developer to post documentation about training data, so record source, date range and data types for each documentation set at intake [7]. This page is general information, not legal advice. Confirm requirements with counsel for your jurisdiction and use case.

Delivery formats that keep documentation joinable

Documentation is only useful if it stays attached to stable object identifiers. Ask for a manifest keyed on fully qualified names (database.schema.table.column), with the documentation set as JSONL or Parquet and the metric layer as the original YAML in a Git bundle so history survives.

Warehouse-native sharing is one route when the schema lives in a cloud warehouse. Snowflake Secure Data Sharing exposes read-only objects to a consumer account without copying data [6], but confirm that column comments travel with shared objects, as tags are typically not shared and that your license covers derived copies you make for training. For multi-turn analytics, extend the same identifiers into conversational text-to-SQL data, and hold back a slice for private text-to-SQL evaluation sets. Document the final package with a datasheet for datasets.

Where SourceX fits for schema documentation sourcing

SourceX sources operational datasets from US companies on request, including engineering records, documents, and finance and legal workflows, and it manages the licensing and any ongoing purchases. Nothing is held in stock, and a request does not guarantee a match. You describe the documentation you need, not the business; every release is approved by the supplying company, and each dataset is rights-reviewed and delivered under a license that defines records, uses, term and delivery. To scope a request, start at the SourceX buyer intake, or browse the wider tabular, time-series and transactional data guide and the AI data hub.

Source schema documentation for your text-to-SQL model

Describe the dictionaries, glossaries, metric layers and paired databases you need, and the license uses you require. SourceX looks for US businesses that hold that data, assesses data and licensing permissions, and nothing is contracted until a supplier agrees. Describe the schema documentation you need.