Schema versioning

Every request Alderstone sends, and every success response your middleware returns, carries a schemaVersion field. It exists so that breaking contract changes can be rolled out safely, without ambiguity about which shape either side is speaking.

Current version

The contract version is "1" for both apps:

{ "schemaVersion": "1" }

Rules

• Alderstone sends "1" on every outbound request body.
• Your middleware must echo "1" on every success response; responses without it fail validation.
• Error responses should include schemaVersion too when returning JSON (recommended, and the standard error body includes it).

Staying forward compatible

Alderstone may add optional fields to request bodies in minor contract updates without changing the version. Your middleware should therefore ignore unknown fields instead of rejecting requests that contain them. Strict schema validation that fails on extra keys will break on routine additions.

Breaking changes (removed fields, changed types, new required fields) increment the version. Alderstone will document the migration path on this page before any new version is enforced, so an integration built against "1" keeps working until you're ready to move.