Define the canonical JSON response envelope and error shape #5

New issue

Closed

opened 2026-07-01 00:57:30 +00:00 by manlycucumber · 1 comment

manlycucumber commented

2026-07-01 00:57:30 +00:00

(Migrated from github.com)

Problem

Every endpoint must return a consistent, documented JSON structure so clients can rely on a stable contract. Without a shared envelope and error shape, each handler would invent its own format and break the contract-freeze goal later.

Acceptance criteria

A response envelope defines top-level fields for payload, the data-version stamp, and request echo (date/system/calendar/etc. where relevant).
A single error shape carries a stable machine code, human message, and HTTP status.
All error responses across the service use this shape.
The envelope and error shape are covered by serialization tests.

Notes

Keep the envelope minimal and additive-only so future fields never break existing clients.

## Problem Every endpoint must return a consistent, documented JSON structure so clients can rely on a stable contract. Without a shared envelope and error shape, each handler would invent its own format and break the contract-freeze goal later. ## Acceptance criteria - [ ] A response envelope defines top-level fields for payload, the data-version stamp, and request echo (date/system/calendar/etc. where relevant). - [ ] A single error shape carries a stable machine code, human message, and HTTP status. - [ ] All error responses across the service use this shape. - [ ] The envelope and error shape are covered by serialization tests. ## Notes Keep the envelope minimal and additive-only so future fields never break existing clients.

manlycucumber commented

2026-07-03 05:31:30 +00:00

(Migrated from github.com)

Delivered in #133 (squash-merged to develop).

Delivered in #133 (squash-merged to `develop`).

manlycucumber referenced this issue from a commit

2026-08-05 19:02:25 +00:00

feat: service skeleton, Core wiring, and the /v1/day endpoint (#133)

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

Directorium/Api#5

No description provided.

Rows
Columns