11. Appendix

11. Appendix#

The Appendix provides reference materials, reserved conventions and developer tools for teams implementing or integrating JsonDispatch.

It’s meant as a quick lookup section — not something you memorize, but something you check when building middleware, validation tools or test clients.

11.1 Reserved Headers (Response Only)#

These headers are core to JsonDispatch and reserved for server responses. They should never be redefined for other purposes.

Header	Direction	Required	Description
Content-Type	Response	✅	Media type of the response payload (`application/json; charset=utf-8` for JsonDispatch envelopes; native media types for files/streams)
X-Api-Version-Selected	Response	✅	Full semantic version of the server’s JsonDispatch implementation
X-Request-Id	Response	✅	Unique identifier generated by the server for this specific request/response
X-Correlation-Id	Response	⚪	Optional; groups multiple related requests under one workflow
X-RateLimit-Limit	Response	⚪	Optional; maximum requests allowed in the current window
X-RateLimit-Remaining	Response	⚪	Optional; requests remaining in the current window
X-RateLimit-Reset	Response	⚪	Optional; Unix timestamp when the rate limit resets
RateLimit-Limit	Response	⚪	Optional; IETF Draft alternative for maximum requests allowed
RateLimit-Remaining	Response	⚪	Optional; IETF Draft alternative for requests remaining
RateLimit-Reset	Response	⚪	Optional; IETF Draft alternative (seconds until reset, not timestamp)
RateLimit-Policy	Response	⚪	Optional; IETF Draft policy format (e.g., `1000;w=3600`)
Retry-After	Response	⚪	Optional; seconds to wait before retrying (for 429 and 503 responses)
Deprecation	Response	⚪	Optional; indicates the endpoint is deprecated (`true` or RFC 8594 date)
Sunset	Response	⚪	Optional; RFC 8594 date when the endpoint will be removed
WWW-Authenticate	Response	⚪	Optional; authentication scheme for 401 responses
traceparent / tracestate	Response	⚪	Optional; W3C Trace Context headers if distributed tracing is enabled

Important

Clients should send X-Api-Version to declare the desired API version. Clients should not send X-Request-Id or X-Api-Version-Selected — these are server-assigned identifiers for traceability and audit purposes.

Example (Response Headers)

Response

Content-Type: application/json; charset=utf-8
X-Api-Version-Selected: 1.3.1
X-Request-Id: aabbccdd-1122-3344-5566-77889900aabb
X-Correlation-Id: order-2025-09-30-777

If you also use W3C Trace Context:

Response

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
tracestate: infocyph=api-2025

11.2 Reserved Keywords (Top-Level JSON Keys)#

JsonDispatch reserves certain top-level fields in the response body. Avoid reusing them for other meanings.

Reserved Key	Purpose
`status`	Overall outcome (`success`, `fail`, `error`)
`message`	Human-readable message
`data`	Primary content (object, array or list of errors)
`code`	Business-level error code (only in `error` responses)
`_references`	Lookup tables for IDs → labels
`_properties`	Metadata describing structure or pagination
`_links`	Navigational or relational links

Tip

If you need more top-level fields, group them under a meta object or use prefixed names (e.g. app_status).

11.3 Middleware & Utility Patterns#

JsonDispatch is language-agnostic. Here’s what a typical implementation might include:

Middleware responsibilities

Attach Content-Type and X-Api-Version-Selected.
Generate X-Request-Id for each request.
Optionally include X-Correlation-Id if workflow-aware.
Enrich logs and tracing context automatically.

Response builders

Provide helper methods like:
- JsonDispatch::success($data, $message)
- JsonDispatch::fail($errors, $message)
- JsonDispatch::error($code, $errors, $message)
Automatically append _links, _properties and _references if provided.

Logging integration

Every log entry should carry X-Request-Id.
Distributed logs can also use X-Correlation-Id for multi-service correlation.

11.4 Minimal JSON Schema for the Envelope (Dev Tooling)#

A lightweight JSON Schema to validate response envelopes. This helps test suites and monitoring agents verify that your API always returns valid JsonDispatch shapes.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://spec.infocyph.com/jsondispatch/v1/envelope.schema.json",
  "title": "JsonDispatch v1 Envelope",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "status": {
      "type": "string",
      "enum": ["success", "fail", "error"]
    },
    "message": { "type": "string" },
    "code": { "type": "string" },
    "data": {},
    "_references": { "type": "object" },
    "_properties": { "type": "object" },
    "_links": { "type": "object" }
  },
  "required": ["status"]
}

This schema validates:

status must always exist.
Reserved fields must use correct types.
No unexpected top-level keys.

11.5 Example cURL Requests (Version & Headers)#

Basic request (client → server)

curl -H 'Accept: application/vnd.infocyph.jd.v1+json' \
  -H 'X-Api-Version: 1.3.1' \
  https://api.example.com/articles/42

Server response (JsonDispatch-compliant)

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Api-Version-Selected: 1.3.1
X-Request-Id: 60c1bbca-b1c8-49d0-b3ea-fe41d23290bd

Body

{
  "status": "success",
  "message": "Article fetched successfully",
  "data": {
    "id": 42,
    "title": "JsonDispatch in Action"
  }
}

Request with correlation (for multi-step workflows)

curl -H 'Accept: application/vnd.infocyph.jd.v1+json' \
  -H 'X-Api-Version: 1.3.1' \
  -H 'X-Correlation-Id: order-2025-10-05-xyz' \
  https://api.example.com/checkout

Server response

Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
X-Api-Version-Selected: 1.3.1
X-Request-Id: 8d4e2a1b-c821-4b97-8430-44c7b9651d79
X-Correlation-Id: order-2025-10-05-xyz

Body

{
  "status": "success",
  "message": "Checkout initiated successfully",
  "data": {
    "order_id": "ORD-2391A",
    "state": "processing"
  }
}

11.6 Developer Notes#

The server is the only authority for JsonDispatch headers. Clients may provide X-Correlation-Id (optional), but never X-Request-Id.
Clients should send X-Api-Version on requests; the server responds with X-Api-Version-Selected.
For JsonDispatch envelope responses, use Content-Type: application/json; charset=utf-8 (vendor media type on responses is optional).
Always include X-Api-Version-Selected in responses — even for errors.
JsonDispatch responses remain valid JSON even for plain application/json clients.

11.7 Response Body Conventions#

To keep payloads portable across SDKs and languages, use these conventions consistently:

Convention	Recommendation
Timestamp fields	Use UTC with ISO 8601 / RFC 3339 format (example: `2026-05-13T09:45:00Z`).
Nullable fields	Use explicit `null` only when the field is still part of the contract; omit fields only when optional and undocumented as always-present.
Numeric identifiers	Keep identifier types stable across versions (don’t switch `id` between integer and string).
Boolean semantics	Use `true`/`false` only for binary state; avoid encoding booleans as `0/1` or `"yes"/"no"`.
Error detail objects	Keep `field`, `code` and `message` stable so clients can automate retries and UX messaging.

11. Appendix

Contents

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#