ApiSutra PHP 0.2.0

JSON object/array identity now survives decoding and is checked against the existing DTO and Shape declarations, including nested values, cached and async responses, pagination items and built-in continuation.

Compatibility

• JSON objects, including {} and objects with consecutive numeric keys, no longer satisfy a strict list declaration.
• JSON arrays no longer satisfy a DTO object input by default.
• Nonempty lists such as ["a"] are rejected as DTO input instead of silently producing a default-valued DTO and losing the supplied values. This check remains active in every configuration; no setting fully reproduces 0.1.1 behavior.
• Use emptyListAsObject: true on the relevant DtoShape, ValueShape::dto or Returns declaration for providers that send [] for an empty object. Required fields still apply. normalizeKeys: true remains the explicit map-to-list conversion option.

Configuration and cost

HydrationConfig::jsonShapeValidation is enabled by default. Setting it to false for a client skips additional JSON shape metadata processing, including built-in continuation. DTO and field declarations do not override the switch; ordinary hydration and input checks remain active.

The decoder uses native JSON parsing with progressive normalization and sparse metadata. Many empty or numeric-key objects can still require substantial memory. Measure peak memory with representative payloads and concurrency; smaller pagination pages and lower concurrency reduce the peak.

Public decoded values remain PHP arrays. Custom transformation boundaries, diagnostics and local normalization permissions are documented in the configuration reference and shape reference.

Validated with 3,286 core tests, Laravel integration, static analysis, documentation checks and no-dev distribution installs. See the changelog.