# Client Contracts Are Prepared at Output Boundaries ## Claim A canonical internal contract stays authoritative and simple when every external-facing representation is derived from it at the moment of output, rather than by mutating or replacing the canonical version to suit one consumer. <!-- atomicity: 1 idea ✓ --> ## Scope & conditions - Holds when the internal representation carries conventions (validation rules, callbacks, provider-specific fields) that external consumers can't or shouldn't process directly. - Requires the transformation to be non-mutating — a copy prepared for output, not a replacement of the stored source. - Breaks down if "preparation" is skipped for convenience and the internal format leaks to external consumers directly, or if so many client-specific variants accumulate that the boundary logic itself becomes the new source of complexity. ## Evidence WordPress 7.1 adds `wp_prepare_json_schema_for_client()` specifically because WordPress's internal ability/REST schemas use server-only conventions (property-level `required` booleans, PHP callback validators) that external validators, JS apps, MCP clients, and AI providers can't safely consume. Core's explicit guidance: "Do not replace the schema stored by an ability with the prepared version. Keep the canonical WordPress schema for server-side use and prepare a copy only when sending it to a client." The helper is applied automatically to Abilities REST responses and AI Client function declarations, and recommended for any custom integration crossing the same PHP-to-external boundary. ## Links - [[3. Resources/Permanent Notes/Canonical Sources Reduce Interface Drift]] — because extends; both claims argue that a single governed source generating derived, per-surface representations beats maintaining separate copies per consumer — one in business content, this one in API schemas - [[3. Resources/MOCs/Open Source Governance MOC]] — because applies-in; Core choosing to solve this once, centrally, rather than leaving every ability author to reinvent client-schema translation ## Tests / falsifiers - Find an ability or endpoint that skips preparation and ships its raw internal schema to an external client directly — check whether that consumer actually breaks, confirming the boundary matters in practice and not just in principle. - Watch for schema drift: if the canonical schema and a "prepared" copy diverge and someone edits the copy directly to fix a client bug, that's the pattern failing — the derived copy becoming a second source of truth. ## Maintenance - Last tended: 2026-08-16 - Next review: 2026-11-16 ## Source - [[3. Resources/Readwise/Articles/JSON Schema Preparation for Client Compatibility in WordPress 7.1]] — Milana Cap, Make WordPress Core dev note, 2026-07-31.