Skip to main content

​
Schema Versions

Schema growth is expected. The public contract should stay stable even as internal data structures expand.
  • keep a versioned public contract
  • separate stable core fields from extensible attributes
  • avoid breaking top-level field names casually

​
Stable core concepts

  • project
  • program
  • organization
  • dashboardSummary
  • applicationWindow

​
Extensibility direction

When new fields appear, prefer adding them in a way that does not break existing consumers. Typical buckets:
  • summary fields
  • attributes
  • relations
  • provenance

​
Documentation rule

Every schema addition that changes what users or agents can query should be reflected in:
  • Mintlify docs
  • API reference
  • MCP tool descriptions
  • CLI help text
  • changelog