WP Content Contracts
PHP · JSON SCHEMA · WP-CLI
Headless and hybrid WordPress teams need external consumers held to a shape without moving authorisation out of WordPress. This framework-free PHP library makes the contract an artefact you can export as JSON Schema and check from CI.
- Maintainer
- Pixy Puala
- Vertical
- API contracts · Headless WordPress
- Year
- 2026
- Role
- Open source
- Stack
- PHP
- Status
- ● Public repo
- Verified
- Source on GitHub
Problem
Producer and consumer drift silently: a field is renamed, a nullable becomes required, and the break surfaces days later in someone else's frontend. Without a machine-checkable contract, the only detection mechanism is a user complaint.
Constraints
Decisions
Round-trip equality is a test, not a hope
A contract exported to JSON Schema draft 2020-12 and re-imported must compare equal via Contract::equals(). Lossy export is caught by the suite rather than by a consumer.
Ship a WP-CLI checker
Defining a contract is easy; enforcing it is the value. The CLI checks a live API and exits non-zero on violations so it works as a CI gate.
Framework-free on purpose
No framework dependency means the library drops into any PHP consumer — including ones that are not WordPress at all.
Build
Stack
- ▸ PHP · Composer · framework-free
- ▸ JSON Schema draft 2020-12 export / import
- ▸ Contract validator · response checker
- ▸ WP-CLI command · non-zero exit on violations
- ▸ PHPUnit
Tooling
- ✓ kept Composer · WP-CLI · GitHub Actions
Results · Measured
The WP-CLI command was run against a live WordPress 7.0.2 install checking an independent live API, reporting conformance (exit 0) and 10 violations (exit 1) correctly. The run surfaced and fixed three real defects — recorded in docs/RUNTIME-VERIFICATION.md.
Tradeoffs
Only unauthenticated wp_remote_get checks are supported. Authenticated APIs need a credential story that is deployment-specific, so it is a documented boundary rather than a half-built auth layer.