JsonDispatch – Developer Guide

Welcome! This site hosts the JsonDispatch specification and examples.

• What is it? A lightweight, production-ready JSON response spec.

• Why use it? Stable envelope (success / fail / error), server-generated tracing with X-Request-Id and clear version signaling via request X-Api-Version and response X-Api-Version-Selected.

Contents

• 1. Introduction
  • 1.2 Why another spec?
  • 1.3 Core Principles
• 2. Media types & versioning
  • 2.1 Media type explained (with examples)
  • 2.2 Versioning strategy (major/minor/patch)
  • 2.3 Required & recommended headers
  • 2.4 Version selection & migration
  • 2.5 Non-JSON responses (reports & exports)
  • 2.6 Authentication & authorization
• 3. Request & Response Identification
  • 3.1 X-Request-Id – server-generated trace ID
  • 3.2 X-Correlation-Id – linking related operations
  • 3.3 Distributed tracing (traceparent, tracestate)
  • 3.4 Rate limiting
• 4. Response Envelope (The Outer Wrapper)
  • 4.1 Top-Level Members at a Glance
  • 4.2 status — Success, Fail or Error
  • 4.3 message — Keep It Human-Friendly
  • 4.4 data — Your Actual Payload
  • 4.5 _references — Turning IDs Into Meaning
  • 4.6 _properties — Describing Data Context
  • 4.7 _links — Pagination and Beyond
  • 4.8 Envelope Summary
• 5. Response Examples
  • 5.1 A Simple Success Response
  • 5.2 A Fail Response (Validation Issue)
  • 5.3 An Error Response (System Failure)
  • 5.4 Paginated Collection Response
  • 5.5 References in Action
  • 5.6 Async & long-running operations
  • 5.7 Bulk operations & partial success
• 6. Error Handling
  • 6.1 fail vs error — Know the Difference
  • 6.2 Error Object Structure
  • 6.3 Field-level vs request-level errors
  • 6.4 Error Codes (code) — Symbolic and Actionable
  • 6.5 Recommended HTTP Status Mapping
  • 6.6 Key Takeaways
• 7. Properties & References
  • 7.1 _properties — Describe Your Data, Not Just Send It
  • 7.2 _references — Replace IDs with Meaning
  • 7.3 Choosing Between Them
  • 7.4 Example — Combined in One Response
  • 7.5 Nested _references Example
• 8. Links
  • 8.1 _links for Pagination
  • 8.2 _links for Related Resources
  • 8.3 _links with Metadata (Enriched Links)
  • 8.4 Best Practices for _links
  • 8.5 _links for Files and Downloads
  • 8.6 _links for Inline Media (Thumbnails, Avatars, Previews)
• 9. Compatibility & Evolution
  • 9.1 Core Compatibility Rules
  • 9.2 How to Introduce Breaking Changes
  • 9.3 Recommended Evolution Workflow
  • 9.4 Version Lifecycle Enforcement
• 10. Best Practices
  • 10.1 Always log X-Request-Id
  • 10.2 Deprecation Lifecycle (Field or Endpoint Evolution)
  • 10.3 Response Media Types & Fallbacks
  • 10.4 Security Headers & CORS Policy Recommendations
  • 10.5 Use _properties and _references Generously
  • 10.6 Operational Logging, Correlation, Monitoring & Security
• 11. Appendix
  • 11.1 Reserved Headers (Response Only)
  • 11.2 Reserved Keywords (Top-Level JSON Keys)
  • 11.3 Middleware & Utility Patterns
  • 11.4 Minimal JSON Schema for the Envelope (Dev Tooling)
  • 11.5 Example cURL Requests (Version & Headers)
  • 11.6 Developer Notes
  • 11.7 Response Body Conventions