On this page
Start with the row grain
Write one sentence that answers: “What does one row represent?” It might be an event, a document version, a sensor observation, or an item in a catalog. Do not use “one record” unless the source system uses that term consistently. A timestamp does not become a unique key merely because it looks precise, and a readable label does not become an identifier merely because it is easy to scan.
| Question | Record in the contract |
|---|---|
| What is the row grain? | A plain-language definition of one row |
| What identifies a row? | Key fields, composite keys, or “no stable key known” |
| What links tables? | Join fields, cardinality expectation, or no link |
| What is the coverage? | Source, collection period, and known exclusions |
| What can change? | Version, update, correction, or append behavior |
The W3C, (opens in a new tab) describes rows, columns, cells, and metadata as parts of an annotated table. Use that model to describe structure, not to imply that a schema proves the quality or rights of a value.
Build a column dictionary that can be checked
Keep the source field beside a human-readable definition. Record a logical type, not only a storage type. “String” does not say whether a value is a country code, a free-text note, or an opaque identifier. Give the field a boundary that another reviewer can test.
| Dictionary field | What to specify |
|---|---|
column_name | Exact source header, including case and punctuation |
description | What the field means at the row grain |
logical_type | Identifier, date-time, category, measurement, text, or other type |
unit_or_format | Unit, timezone, date representation, or encoding rule |
allowed_values | Code list, range, pattern, or “free text” |
requiredness | Required, conditional, optional, not applicable, or unknown |
missingness | Meaning of blank, null, sentinel, withheld, and unavailable values |
source_field | Upstream field or transformation source |
transform_rule | Rename, cast, normalize, aggregate, or no transformation |
quality_check | A check that can pass, fail, or remain unknown |
Do not turn 0, false, or an empty string into a universal missing-value code. If the source uses sentinels, document them and preserve the difference between “not applicable” and “not observed.” The UK Government, (opens in a new tab) names distinct quality dimensions, so keep those dimensions separate in the dictionary and the review record.
Make structural metadata explicit
For a delimited file, record the delimiter, quote rule, encoding, line-ending expectation, header behavior, decimal convention, date-time convention, and treatment of embedded line breaks. For a spreadsheet, record sheet names, hidden sheets, formulas, and whether displayed values or formulas are the review target. For a JSON export, record the object shape, array meaning, nullable fields, and versioning rule.
The W3C, (opens in a new tab) recommends descriptive and structural metadata, provenance, and data-quality information. The UK Government, (opens in a new tab) points to CSV on the Web metadata for describing CSV contents and structure. Those sources support a machine-readable description, but they do not choose the correct business definition for a private field.
| Unknown state | Record instead of guessing |
|---|---|
| Timezone not documented | Timezone unknown; source owner question open |
| Join key appears in both files | Cardinality not checked; relationship remains unknown |
| Header changed between exports | Schema version and transformation need review |
| Displayed spreadsheet value differs from formula | Review target must be selected and recorded |
Use a decision table before any sample moves
Run the contract against an export manifest or a synthetic fixture first. Keep raw sensitive records out of this step. “Pass” means that the named structural check has evidence. It does not mean that the collection is complete, accurate, licensed, or suitable for a particular model.
| Structural finding | Decision | Next action |
|---|---|---|
| Grain and key are documented | Continue | Test shape and relationship rules |
| Grain is clear but no stable key is known | Conditional | Preserve source identifiers and note the limitation |
| Requiredness or null meaning is unknown | Hold | Ask the data owner for the codebook |
| Headers or types change between files | Hold | Version the schema and identify the transformation |
| Sensitive fields are not classified | Do not sample | Classify fields and set an approved handling boundary |
| Structural checks pass | Structural review ready | Keep rights, privacy, and accuracy as separate work |
General information, not legal advice.
Validate shape without inspecting private values
The first pass can inspect a file manifest, headers, column counts, declared types, hashes, and relationship metadata. A synthetic fixture can exercise quoting, dates, null states, and multi-table joins without exposing a real person, customer, employee, patient, or message. If a real sample is necessary, use an owner-approved, redacted artifact with a documented audience and deletion path.
Keep the review record at field level
- Record the check name, expected rule, observed state, source reference, and unresolved question.
- Use a neutral artifact ID instead of pasting a private row into a public worksheet.
- Treat a structural schema as separate from a de-identification decision.
- Use the data card template for collection context and the data provenance log for source and transformation history.
A metadata description can explain structure while leaving privacy, rights, and accuracy questions open. Keep those questions visible rather than collapsing them into one quality label.
Close the review with a qualified next step
Before asking for an appraisal, confirm that you have authority to describe the collection, identify exclusions, and choose the intended use. If the scope is a supported non-health collection, use the appraisal route after preparing the dictionary. That route is a request for review, not automatic acceptance, a quote, a buyer match, a legal opinion, or a license. Do not upload sensitive raw records merely to test whether the schema is understandable.
Takeaways
- Define row grain, keys, relationships, and exclusions before discussing quality.
- Give every field a meaning, type, unit, missingness rule, and check.
- Keep structure, privacy, rights, accuracy, and demand as separate review questions.
- Use synthetic or metadata-only artifacts first, then escalate only with documented authority.
General information, not legal advice.