JSON Schema Guide
JSON Schema turns an example payload into an explicit contract. Instead of saying that an API returns "a customer object", a schema can describe which fields exist, which fields are required and what type each field should have.
Generated Schemas Are Drafts
A generator can infer structure from the values it sees. It can detect objects, arrays, strings, numbers, booleans and nulls. It cannot know every rule in your business domain. A generated schema is a starting point that should be reviewed by someone who understands the API.
{
"type": "object",
"required": ["id", "email"],
"properties": {
"id": { "type": "integer" },
"email": { "type": "string", "format": "email" }
}
}Required Fields Need Judgment
If a field appears in one example, a generator may mark it as required. That is useful for one known payload, but production APIs often have optional fields. Review every required field and remove values that are not guaranteed by the API contract.
Arrays Need More Than One Example
For arrays, a single item only shows one possible shape. Better samples include multiple realistic records. If one item has a field and another item does not, the schema should usually treat that field as optional within the array item object.
Validation Is A Conversation
Schema validation is best used in API tests, documentation, integration checks and contract reviews. It helps teams catch accidental breaking changes before a frontend, webhook consumer or reporting job fails later.
Before sharing schemas or payloads, remove live tokens, private identifiers and customer data. Keep the shape; replace sensitive values.
Use Formalint
Use the Formalint JSON Schema Generator to draft a schema from a sample payload. For raw payload cleanup, start with the JSON Formatter.