Your hand-written JSON Schema is lying to your API. Mine was.

A JSON Schema written manually for a payment webhook payload once functioned well, but issues arose when the provider added a new field. The schema had been set to disallow additional properties with `additionalProperties: false`, resulting in validation failures at an odd hour. The schema itself was not inherently wrong at the time of creation, but it became incorrect once reality changed and the developer did not update it accordingly.

Hand-written schemas are prone to drifting out of sync with the actual data, as they are static snapshots reflecting the data structure at the moment they were written. Because the schema and the payloads reside in separate repositories, manual updates are often neglected. To address this issue, it is recommended to adopt a sample-first approach to schema creation.

By starting with real sample responses and automatically generating a draft 2020-12 schema with marked required fields and a plain-English explanation of validation rules, the schema can be more accurately reflected the actual data. Regularly tightening the schema based on practical knowledge of optional fields, string enums, and data types (such as distinguishing integers from floating-point numbers) can help maintain its relevance.

Reading the schema aloud can also aid in its ongoing maintenance. Additionally, integrating schema validation into CI pipelines and utilizing structured output contracts with language models can enhance the overall schema management process. However, it's important to note that automated schema generation cannot infer business rules or deduce nuanced constraints from limited samples.

Manual reviews are still necessary to ensure accuracy. Furthermore, the generated schemas adhere to the draft 2020-12 specification, so compatibility adjustments may be required if working with draft-04 tools. To begin, it's advisable to use the most complex and field-rich JSON response available and feed it into a schema generator.

If the resulting schema accurately reflects the data structure and identifies any discrepancies in test coverage, the workflow should be implemented for better schema management.