A JSON example can look self-explanatory while leaving the consumer unsure what was requested, which fields are optional and whether the result is complete.
Quick answer: Show the relevant input, schema or version, field meanings, empty and partial-result behavior, and whether the example is synthetic or observed. Keep credentials and private records out of the example. A plausible sample demonstrates a contract only when its scope is clear.
Label the artifact
The following is a synthetic response from a hypothetical batch-extraction service. It is not an API.market endpoint contract or an executed provider result.
{
"status": "partial",
"items": [
{"source_id": "sample-a", "text": "Synthetic article text"},
{"source_id": "sample-b", "text": null, "reason": "unavailable"}
]
}
The surrounding documentation would need to define what partial means, whether null is allowed and what unavailable establishes.
Add the consumer questions
| Context | Question answered |
|---|---|
| Request | Which input produced this shape? |
| Version | Which contract does it illustrate? |
| Field definition | What can the consumer infer? |
| Completeness | Which items succeeded or remain unresolved? |
| Provenance | Synthetic or captured from an identified test? |
| Next step | How should a partial result be handled? |
Do not imply a billing or retry policy merely by showing a reason field.
Include a meaningful alternative
Pair the happy path with a documented empty, partial or rejected result. Keep examples consistent with the actual selected product.
If a captured response is transformed for readability, state what was changed and preserve an appropriate original reference for review.
Check the downstream assumption
A consumer should not treat a parseable envelope as proof that every item succeeded. Inspect the field that determines usable output.
The format-versus-task guide and tool-boundary guide explain why those distinctions matter beyond documentation.
I'm Shashank Agarwal, creator of API.market and founder and CEO of Noveum AI. Follow my work on LinkedIn. Drafted with AI assistance.
Top comments (0)