Saved by the Schema: Using JSON Schema to Document, Test, and Debug APIs

Summary

Heroku uses JSON Schema to define Platform API response structures, generate documentation, and validate endpoint behavior. A CI-invoked rake task detects schema changes and uses prmd to generate Markdown API reference material, while committee tests API responses with assert_schema_conform. Those tests exposed an edge case in Enterprise usage data: dyno values with many decimal places were parsed by Oj as BigDecimal and serialized as quoted strings, whereas integer and ordinary float values remained numbers. Heroku traced this behavior through MultiJson and configured Oj with bigdecimal_load: :float, because the endpoint had sufficient precision at 15 decimal places and its schema required a number. The conforming test then passed, confirming that the schema and generated documentation matched returned API values.

Takeaways

1. 1

   The CI rake task detects JSON Schema changes and uses prmd to generate the public Platform API Reference in Markdown.

2. 2

   Oj serialized a BigDecimal dyno value as a quoted string, causing committee's assert_schema_conform check to reject it as not a number.

3. 3

   Setting MultiJson.load_options to { bigdecimal_load: :float } made the schema conformance test pass for the affected endpoint.