Understanding Dynamic Schemas

A dynamic schema means the API's queryable data model is discovered at runtime rather than hard-coded into your application. Instead of knowing at development time what fields are available, your application queries the /v1/meta endpoint to learn the current structure, then builds queries accordingly.

This is fundamentally different from traditional REST APIs where you write code against a fixed set of known fields.

The Reporting API schema is backwards compatible — Square does not remove or rename fields in breaking ways. However, the schema does grow over time as new measures, dimensions, and cubes are added. Dynamic discovery lets your application automatically pick up these additions without redeployment.

Implement a discovery layer that sits between your application logic and the API:

Layer Responsibilities:

• Application Layer: UI, business logic, and reporting components
• Discovery Layer: Metadata caching, query validation, and error handling
• API Layer: Schema discovery and query execution

1. Discover on startup: Fetch metadata on application startup or periodically to surface new fields
2. Cache metadata appropriately: Balance freshness with API load (1-24 hour TTL)
3. Build dynamic UIs: Populate options from metadata, not hard-coded lists
4. Validate before executing: Check queries against cached metadata to catch errors early
5. Refresh after errors: If a query fails with "not found", invalidate cache and retry

For implementation details — caching code, validation patterns, and parsing examples — see Metadata Discovery.