Systems and records
Dataset sample and full package consistency: one schema contract for both
By SourceX Editorial · Updated
9 sections
Short answer
Keep a dataset sample and its full package consistent by making both reference one versioned schema contract: the same field names, types, missing-value codes, identifiers, file layout and hashes, checked by the same runnable validator. The sample is a small instance of the contract, not a preview of it. Any difference in the full delivery must arrive as a declared new contract version, never as a surprise.
License terms
Dataset sample full package
Key takeaways
- A sample is useful only if it is the first conforming instance of the same written contract the full delivery must meet.
- Put the contract identifier and schema version in both manifests and run one validator, at one version, on both packages.
- Renames, type or format changes, new required fields and undeclared code values need a new major version and a new sample.
- Ship relative paths, code lists, hashes and the validator command so the buyer can check the package without the supplier.
- When the full delivery fails, decide between re-export, remap with a new version, or rejection, and record who agreed it.
How do you keep sample and full-delivery dataset schemas consistent?
Write the schema down once as a contract file, give it an identifier and a version, and require the sample and the full delivery to name that same identifier and version in their manifests. Then run one validator, at one version, against both. If the sample passes and the full delivery fails, the delivery is out of contract, and the conversation is about who fixes it rather than what was meant.
Most sample disappointments are not about record quality. They come from small structural changes between the two: a field renamed during a later export, a date written in a different format, a code list that grew, an identifier scheme that changed when the supplier switched tools. The buyer evaluated one shape and received another, and the integration code written against the sample breaks on day one.
The fix is to stop treating the sample as a preview and start treating it as the first conforming instance of a package specification. Everything a buyer learns from the sample then transfers to the full delivery, because both are held to the same written rules.
Timing matters. Before the buyer commits, the supplier can still change its export at little cost and the buyer has not yet written loaders, feature code or evaluation splits against the sample. After commitment, every structural surprise lands on work already done. A contract agreed at sample time is the cheapest point in the whole purchase to settle structure, which is why this page focuses on the one-time step from sample to first full delivery rather than on the run of later deliveries a recurring feed contract governs.
The contract also changes what a sample review can conclude. Without one, a reviewer can only say the sample looked reasonable. With one, the reviewer can say the sample conforms to version 1.2.0 of a named contract, and that statement can be tested again, mechanically, on every file of the full delivery.
Eight ways a sample quietly differs from the delivery it previews
Each pattern below can pass a visual inspection of the sample and still break the buyer's pipeline when the full package lands. The right-hand column names the check that catches it, which becomes a line in the checklist further down.
| Drift | Sample shows | Full delivery shows | Check that catches it |
|---|---|---|---|
| Renamed field | wo_status | status, after a later export template | Field name set equality against the contract |
| Type or format change | created_at as ISO 8601 with offset | created_at as local time with no offset | Per-field type and format validation |
| Missing-value encoding | Empty string for unknown priority | NA, null and blank mixed in one column | Declared missing-value list per field |
| Code list growth | Five status values | Seven values, two never documented | Enum or categories check with an explicit unknown rule |
| Identifier scheme change | Work order IDs as stable surrogate keys | Native system IDs, or keys reissued per batch | Primary key format, uniqueness and cross-file join test |
| Layout change | One file per table | Partitioned folders by month with new names | Manifest paths and resource roles match the contract |
| Pseudonym drift | Same customer token across files | Tokens regenerated per batch | Foreign key resolution across resources and batches |
| Hand-cleaned sample | Trimmed text, no duplicates | Raw notes, duplicate lines present | Same pipeline version recorded in both manifests |
What the shared contract file has to pin down
The contract is a machine-readable descriptor plus a short human document that explains meaning. Open formats already define most of the parts, so there is no need to invent a format. The Frictionless Table Schema specification describes fields with a name, type, format and constraints, a schema-level list of strings to treat as missing values, a primary key and foreign keys that reference other resources. Its Data Resource specification gives each file a path that is either a URL or a relative POSIX path, plus a byte count and a hash, MD5 by default with other algorithms named by a prefix such as sha256.
At a glance
What the shared contract file has to pin down
MLCommons Croissant covers the same ground for machine learning datasets: a distribution of file objects with sha256 checksums, and record sets whose fields have a data type, with IDs that must be unique within the dataset. Either format works. What matters is that the contract states the following, and that both the sample and the full delivery point to it.
- Contract identifier and schema version, for example a semantic version string, recorded in every package manifest.
- Content version of each delivery, separate from the schema version, so a new batch does not look like a new structure.
- Every resource: its role (records, events, code list, documentation), its relative path pattern and its file format and encoding.
- Every field: name, type, format, unit, plain-language meaning, whether it is required, its missing-value codes and its allowed values or categories.
- Keys: the primary key of each resource and every foreign key between resources, including which pseudonymized tokens must stay stable across files and batches.
- Integrity: the hash algorithm, the manifest format and the expected record counts per resource.
- Validator: the tool and the version of it that both the supplier and the buyer will run, with the exact command.
The sample to full schema compatibility checklist
Run every check on the sample when it arrives and again on the full delivery. A check marked blocking means the package is out of contract and should not be accepted as is; a warning means the difference is allowed by the contract but should be reviewed. The evidence column says what the supplier ships so the buyer can repeat the check without asking.
| Check | What is compared | Pass rule | Evidence shipped | Severity |
|---|---|---|---|---|
| C1 Contract identity | Contract ID and schema version in each manifest | Identical in sample and full | Manifest file in the package root | Blocking |
| C2 Resource set | Resource names, roles and path patterns | Same set; extra resources only if declared optional | Manifest listing every file with its role | Blocking |
| C3 Field set | Field names per resource | Exact match; no undeclared extra fields | Contract descriptor | Blocking |
| C4 Types and formats | Declared type and format per field | Every value parses as declared | Validator report per file | Blocking |
| C5 Missing values | Codes used for absent data | Only the declared codes appear | Per-field null and missing counts | Blocking |
| C6 Allowed values | Enumerations and code lists | Values within the list or mapped to a declared unknown code | Shipped code list files with versions | Blocking if unmapped |
| C7 Keys | Primary key uniqueness and foreign key resolution | No duplicate keys; every reference resolves | Key report and orphan count | Blocking |
| C8 Token stability | Pseudonymized IDs that appear in both packages | Same entity, same token, where the contract says tokens are stable | Overlap list of sample IDs present in the full delivery | Blocking |
| C9 Integrity | Bytes and hashes of every file | All hashes match the manifest | Manifest with algorithm-prefixed hashes | Blocking |
| C10 Pipeline parity | Preparation pipeline and validator versions | Same versions, or a change log entry | Build record in the manifest | Warning |
Which changes between sample and full delivery need a new contract version?
Any change that would make the buyer's code fail needs a new major contract version agreed before delivery; additions of data do not. The Frictionless Data Package version recipe is a useful default: it calls for a major version when a field is added, removed or reordered, when a field type or format changes, or when a constraint becomes more restrictive, a minor version when new data is added or a constraint is relaxed, and a patch version for corrections to existing values or descriptive metadata. This page departs from the recipe in one place: it tracks added records with a separate content version rather than a minor version, so a new batch does not look like a structural change.
Apache Avro's schema resolution rules show why renames and new required fields are the dangerous cases. Avro matches record fields by name, ignores writer fields the reader does not know, fills in a reader field that has a default, and signals an error when the reader expects a field with no default that the writer did not provide. A renamed field therefore behaves like one field dropped and another added, and the buyer's reader fails unless the contract supplied a default or an alias.
Two practical rules follow. First, the sample should be produced under the same major version the full delivery will use. Second, if the supplier knows a structural change is coming, for instance a system migration between the sample and the full export, the new version should be published and a fresh sample cut under it before the buyer commits.
| Change between sample and full | Version step | Allowed without a new sample? |
|---|---|---|
| More records in the same resources | Content version only | Yes |
| A new optional resource the buyer can ignore | Minor | Yes, if declared in the contract |
| A relaxed constraint, such as a longer text limit | Minor | Yes, with a change note |
| A field added, removed, renamed or reordered | Major | No |
| A type, format or unit change | Major | No |
| A code list value added without a mapping | Major unless an unknown code is declared | No |
| A corrected value in existing records | Patch | Yes, with a change note |
Worked example (illustrative): a work-order package that passes, then fails
The records and counts in this example are invented to show the checks working; they do not describe any real dataset. A supplier offers a field-service package with two resources: work_orders and work_order_lines. The contract, version 1.2.0, declares work_order_id as a required string matching a surrogate pattern and the primary key of work_orders; status as a string limited to open, scheduled, completed and cancelled, with unknown as the declared fallback; completed_at as an ISO 8601 datetime with offset; labor_minutes with an empty string as its only missing-value code; and technician_token as a pseudonym that must stay stable across files.
Expressed as JSON Schema for one work-order record, the contract lists the required properties and sets additionalProperties to false. The JSON Schema validation specification defines required as a list of property names that must all be present, and the core specification applies additionalProperties to any property not covered by properties or patternProperties, so a false value rejects any field the contract does not name. The table compares one sample record that passes with the matching full-delivery record that fails.
- Outcome: the full delivery is out of contract on five checks and in contract on one. Every failure has a named rule, so the supplier can fix the export rather than debate what the sample implied.
- Fix path: re-export with the original date format and token map, add crew_size and completed_pending_invoice through a version 2.0.0 contract with a mapping for the new status, then cut a new sample under 2.0.0.
- What the buyer keeps: the validator report for both packages, filed with the contract version they were checked against.
| Field | Contract rule | Sample value (passes) | Full-delivery value (fails) | Check and result |
|---|---|---|---|---|
| work_order_id | Required, pattern W-8 digits, unique | W-00004812 | W-00004812 | C7 pass; the same ID appears in both |
| status | One of open, scheduled, completed, cancelled or unknown | completed | completed_pending_invoice | C6 blocking; undeclared value with no mapping |
| completed_at | Datetime with UTC offset | 2025-03-04T14:22:09-05:00 | 03/04/2025 2:22 PM | C4 blocking; format changed in a later export |
| labor_minutes | Integer; missing value is an empty string | 95 | NA | C5 blocking; undeclared missing code |
| technician_token | Stable pseudonym across files | t_7f3a91 | t_19be02 for the same technician | C8 blocking; tokens regenerated per batch |
| crew_size | Not in the contract | absent | 2 | C3 blocking; extra field rejected by additionalProperties false |
Is the package portable enough to check offline, with no supplier access?
Yes, if the package carries everything the validator needs and nothing points back into the supplier's environment. Portability is a property of the package, and the checklist above only works if the buyer can run it alone, offline, on the day the files arrive.
That means relative paths inside the package rather than links to a supplier file share, code lists shipped as files rather than referenced by an internal table name, the contract descriptor included in the package root, and hashes for every file so the buyer can prove nothing changed in transit. The Data Resource specification's rule that a path is either a fully qualified URL or a relative POSIX path, and never a mix of both within one path array, is a good default for any format.
A simple test: hand the package to an engineer who has never spoken to the supplier and ask them to load it, validate it and rebuild every join from the documentation alone. Any question they have to ask the supplier is a gap in the contract.
Checklist · 5 items
- Package root contains the contract descriptor, the manifest and a readme with the validator command.
- Every path in the manifest resolves inside the package.
- Every code value used in the records appears in a shipped code list.
- Every foreign key resolves to a record inside the same package or a declared earlier package.
- The validator report the supplier produced is included, so the buyer can compare outputs line by line.
0 of 5 ticked. Tick each item as you go.
What to do when the full delivery fails the sample's contract
Reject, remap or re-version: choose based on whether the difference changes meaning. A format slip such as a changed date layout is a supplier fix and a re-export; the contract is unchanged. A new category that carries real information, such as a status that did not exist when the sample was cut, needs a new contract version with a mapping, and a fresh sample if the buyer's code depends on the field.
Do not accept a full delivery on the strength of a successful sample review when the validator fails, and do not patch the buyer's loader to tolerate the drift silently. Both choices turn a documented contract into an undocumented one, and the next delivery will drift again. Record the decision, the version it produced and who agreed it, alongside the validator reports. Keep the failing records the validator flagged, too: they are the best test cases for the next delivery and the quickest way to show the supplier exactly what drifted.
Write the expectation into the sample terms before the sample is cut: the sample is produced under a named contract version, the full delivery must validate against the same version unless both sides agree a new one in writing, and the supplier ships its own validator report with each package. The commercial and legal wording belongs to counsel; the technical substance is the checklist itself.
Asking for a sample built to the delivery contract
When the data is sourced for a specific request rather than pulled from an existing catalog, the contract can be agreed before any record is extracted, which is the easiest point to get sample and full delivery to match. Format and structure are part of the request, not an afterthought at delivery.
SourceX fills buyer requests from U.S. businesses instead of shipping stock datasets, and its request form covers scope, volume, language, format, timing and licensing needs, so a contract descriptor or this checklist can travel with the request. Structural consistency does not answer whether the records may be licensed; that is settled by the rights review and the signed agreement, and the supplying company approves scope and terms and signs before delivery.
Frequently asked questions
What should the sample to full schema compatibility checklist include?
It should compare contract identity, the resource set, field names, types and formats, missing-value codes, allowed values, keys, pseudonym stability, file hashes and pipeline versions. Each check needs a pass rule, the evidence the supplier ships and a severity. Run it on the sample and again on the full delivery.
How can a buyer check a delivered package with no access to the supplier's tools?
Only if the package is self-contained: relative paths, shipped code lists, the contract descriptor and a manifest with hashes, plus the validator command. Test it by asking an engineer who has never spoken to the supplier to load, validate and join the files from the documentation alone.
Is adding a column between the sample and the full delivery a breaking change?
Under the Frictionless Data Package version recipe, adding a field calls for a new major version. Some readers tolerate extra columns, but a strict contract that rejects undeclared fields will not, so agree the new version and cut a fresh sample before delivery.
Can the sample be CSV while the full delivery is Parquet?
It can, but then the contract must define types independently of the file format and the validator must run on both. Format differences hide type changes, such as dates that are strings in one file and timestamps in the other, so a sample in the delivery format is the safer default.
What valid and invalid examples should a supplier provide with the contract?
At least one record that passes every rule and one deliberately broken record per blocking check, each with the validator output it produces. The invalid examples prove the validator actually enforces the rules rather than accepting everything.
Sources
- Frictionless Table Schema fields carry a name, type, format and constraints; a schema can declare missingValues, a primaryKey and foreignKeys to other resources. Source
- A Frictionless Data Resource path is a URL or a relative POSIX path, never a mix in one path array, and a resource can carry bytes and a hash (MD5 by default, other algorithms by prefix). Source
- The Data Package version recipe calls for a major version when fields are added, removed or reordered or a type or format changes, minor for added data or relaxed constraints, and patch for corrections. Source
- Avro schema resolution matches record fields by name, ignores writer fields unknown to the reader, uses reader defaults, and signals an error when a reader field has no default and the writer lacks it. Source
- Croissant 1.1 describes file objects with sha256 checksums and record sets of typed fields, and requires IDs to be unique within a dataset. Source
- In JSON Schema validation, an object is valid against required only if every listed name is a property of the instance. Source
- In JSON Schema core, additionalProperties validates only properties not matched by properties or patternProperties. Source
Tell us what data you need
Share scope, volume, format, timing and licensing needs. Datasets are sourced on request.