Schema
Option A
Defines constraints
Option B
Less friendly alone
FAQ Guide
API Schema or Example JSON?
Use schema to define rules and example JSON to show practical usage; serious API docs usually need both.
Quick comparison
Example
Option A
Easy to understand
Option B
Can be incomplete
Best docs
Option A
Use both
Option B
Add context
Questions and answers
Why are examples not enough?
They may not show every required rule, type, or edge case.
Why are schemas not enough?
They can be hard for non-specialists to read without examples.
How should AI code be checked?
Compare generated payloads against both schema and examples.