---
title: "Saved by the Schema: Using JSON Schema to Document, Test, and Debug APIs"
description: "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."
---

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

[Heroku](https://yomu.fyi/company/heroku) · Jessie Young · Apr 9, 2019

**Type:** Problem & solution

## 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.

## Context

Heroku needed its public Platform API documentation to remain accurate and its endpoint behavior to conform to JSON Schema definitions. Testing Enterprise usage data revealed that dyno values with many decimal places were returned as strings instead of the numbers specified by the schema.

## Approach / What changed

Heroku used a CI rake task and prmd to generate API documentation from JSON Schema, and committee with assert\_schema\_conform to validate responses. It configured MultiJson's Oj adapter with bigdecimal\_load: :float so BigDecimal values were serialized as numbers.

## Takeaways

- The CI rake task detects JSON Schema changes and uses prmd to generate the public Platform API Reference in Markdown.
- Oj serialized a BigDecimal dyno value as a quoted string, causing committee's assert\_schema\_conform check to reject it as not a number.
- Setting MultiJson.load\_options to { bigdecimal\_load: :float } made the schema conformance test pass for the affected endpoint.

**Tags:** [API](https://yomu.fyi/topic/api), [JSON Schema](https://yomu.fyi/topic/json-schema), [Ruby](https://yomu.fyi/topic/ruby)

- Source: [Heroku](https://www.heroku.com/blog/json-schema-document-debug-apis)
- Source URL: https://www.heroku.com/blog/json-schema-document-debug-apis
- Ingested by Yomu: 2026-09-09T14:27:23.215Z

[Read original post](https://www.heroku.com/blog/json-schema-document-debug-apis)