Guide
Structured Data Testing Handbook
Work through JSON, JSONPath, schema inference, NDJSON, CSV, diffs, and type generation with explicit data-loss boundaries.
Dated source and synthetic-example checks; inferred schemas still require contract review.
Related tools
Identify the actual format
Begin with transport metadata and raw structure. JSON arrays, NDJSON records, CSV tables, and YAML mappings have different parsing and error-recovery rules. Do not convert before identifying the source format.
Separate syntax, shape, and business rules
Syntax says a document parses. A schema describes declared structural constraints. Business validity depends on state, authorization, relationships, and domain meaning. Test these layers independently.
Select and compare data
Use JSONPath to locate specific values, then assert cardinality and path. Use a structural diff for JSON/YAML meaning and a line diff when source presentation matters. Neither comparison chooses the application's compatibility policy.
Infer cautiously
A TypeScript type or JSON Schema inferred from examples only captures observed values. Arrays with mixed objects can reveal optional members, but missing examples cannot establish whether an absent property is valid. Review generated contracts against the authoritative source.
Handle tabular and streaming records
CSV fields are text with quoting rules. NDJSON gives one JSON value per line and supports per-line error reporting. Preserve the distinction when exporting or importing fixtures.
Protect fixture data
Prefer synthetic records. Remove credentials and customer details before pasting, copying, downloading, or attaching reports. Browser-local processing reduces one exposure path but does not address extensions, device compromise, or screen sharing.
Review conversion limits
CSV loses JSON types without an external schema; XML has mixed content and namespaces; flattening needs an unambiguous path convention. Document each mapping before treating a conversion as round trippable.
Worked synthetic record conversion
A CSV export contains id,note followed by 7,"red, blue". Parsing produces two cells, not three. JSON conversion yields {"id":"7","note":"red, blue"}: the id remains a string. A JSONPath query such as $[0].id can select that value after wrapping the object in an array, but selection says nothing about its required type. A schema can assert that separately. A JSON Lines export instead writes one complete JSON value per line; it is not a CSV row stream.
- Retain the source bytes when conversion semantics matter.
- Check syntax, schema constraints, and domain rules independently.
- Assert the JSONPath result count as well as its value.
References
FAQ
Does this handbook replace testing the actual service?
No. It organizes local inspection and test design; runtime behavior requires controlled tests against the owning system.