JSON envelope
The common JSON structure that wraps each Normadata endpoint response with consistent metadata.
Every Normadata API response follows a standard JSON structure — an "envelope" — that gives the client predictability. Regardless of the endpoint invoked (`/v1/verify`, `/v1/verify/tax-id`, `/v1/verify/bank`, etc.), the response body has the same shape: ```json { "contains_pii": true, "processed_at": "2025-10-15T14:32:10Z", "value": { ... }, "warnings": [ ... ] } ``` Fields: - **`contains_pii`**: boolean indicating whether the response contains personally identifiable information. Useful for the client to decide whether to log it. - **`processed_at`**: ISO 8601 UTC timestamp of the exact moment the request was processed. - **`value`**: the endpoint's result — its shape varies depending on what was validated (a tax ID returns format + country; an address returns normalized components). - **`warnings`**: optional array with non-fatal warnings (e.g. `"check_digit_recomputed"`, `"country_inferred_from_pattern"`). The envelope lets a single client-side middleware extract metadata without knowing the specific shape of `value`. It also simplifies logging, observability, and transversal error handling.