Skip to content

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

This page covers dataset sample and full package consistency: one schema contract for both.Illustrative

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.

Eight ways a sample quietly differs from the delivery it previews
DriftSample showsFull delivery showsCheck that catches it
Renamed fieldwo_statusstatus, after a later export templateField name set equality against the contract
Type or format changecreated_at as ISO 8601 with offsetcreated_at as local time with no offsetPer-field type and format validation
Missing-value encodingEmpty string for unknown priorityNA, null and blank mixed in one columnDeclared missing-value list per field
Code list growthFive status valuesSeven values, two never documentedEnum or categories check with an explicit unknown rule
Identifier scheme changeWork order IDs as stable surrogate keysNative system IDs, or keys reissued per batchPrimary key format, uniqueness and cross-file join test
Layout changeOne file per tablePartitioned folders by month with new namesManifest paths and resource roles match the contract
Pseudonym driftSame customer token across filesTokens regenerated per batchForeign key resolution across resources and batches
Hand-cleaned sampleTrimmed text, no duplicatesRaw notes, duplicate lines presentSame 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.

The sample to full schema compatibility checklist
CheckWhat is comparedPass ruleEvidence shippedSeverity
C1 Contract identityContract ID and schema version in each manifestIdentical in sample and fullManifest file in the package rootBlocking
C2 Resource setResource names, roles and path patternsSame set; extra resources only if declared optionalManifest listing every file with its roleBlocking
C3 Field setField names per resourceExact match; no undeclared extra fieldsContract descriptorBlocking
C4 Types and formatsDeclared type and format per fieldEvery value parses as declaredValidator report per fileBlocking
C5 Missing valuesCodes used for absent dataOnly the declared codes appearPer-field null and missing countsBlocking
C6 Allowed valuesEnumerations and code listsValues within the list or mapped to a declared unknown codeShipped code list files with versionsBlocking if unmapped
C7 KeysPrimary key uniqueness and foreign key resolutionNo duplicate keys; every reference resolvesKey report and orphan countBlocking
C8 Token stabilityPseudonymized IDs that appear in both packagesSame entity, same token, where the contract says tokens are stableOverlap list of sample IDs present in the full deliveryBlocking
C9 IntegrityBytes and hashes of every fileAll hashes match the manifestManifest with algorithm-prefixed hashesBlocking
C10 Pipeline parityPreparation pipeline and validator versionsSame versions, or a change log entryBuild record in the manifestWarning

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.

Which changes between sample and full delivery need a new contract version?
Change between sample and fullVersion stepAllowed without a new sample?
More records in the same resourcesContent version onlyYes
A new optional resource the buyer can ignoreMinorYes, if declared in the contract
A relaxed constraint, such as a longer text limitMinorYes, with a change note
A field added, removed, renamed or reorderedMajorNo
A type, format or unit changeMajorNo
A code list value added without a mappingMajor unless an unknown code is declaredNo
A corrected value in existing recordsPatchYes, 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.
Worked example (illustrative): a work-order package that passes, then fails
FieldContract ruleSample value (passes)Full-delivery value (fails)Check and result
work_order_idRequired, pattern W-8 digits, uniqueW-00004812W-00004812C7 pass; the same ID appears in both
statusOne of open, scheduled, completed, cancelled or unknowncompletedcompleted_pending_invoiceC6 blocking; undeclared value with no mapping
completed_atDatetime with UTC offset2025-03-04T14:22:09-05:0003/04/2025 2:22 PMC4 blocking; format changed in a later export
labor_minutesInteger; missing value is an empty string95NAC5 blocking; undeclared missing code
technician_tokenStable pseudonym across filest_7f3a91t_19be02 for the same technicianC8 blocking; tokens regenerated per batch
crew_sizeNot in the contractabsent2C3 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

  1. Package root contains the contract descriptor, the manifest and a readme with the validator command.
  2. Every path in the manifest resolves inside the package.
  3. Every code value used in the records appears in a shipped code list.
  4. Every foreign key resolves to a record inside the same package or a declared earlier package.
  5. 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.

See if your company qualifies