haddowg/json-api

A modern, server-side JSON:API 1.1 library for PHP 8.3+.

v1.0.0 2026-07-13 07:56 UTC

Requires

• php: ^8.3
• psr/container: ^2.0
• psr/http-factory: ^1.0
• psr/http-message: ^2.0
• psr/http-server-handler: ^1.0
• psr/http-server-middleware: ^1.0
• psr/log: ^3.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.64
• nyholm/psr7: ^1.8
• nyholm/psr7-server: ^1.1
• opis/json-schema: ^2.0
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^12.0

Suggests

• opis/json-schema: Enables dev/CI JSON Schema validation of JSON:API request and response documents via Validation\DocumentValidator and the Request/Response validation middleware (^2.0).
• phpunit/phpunit: Required to use the Testing\* assertion helpers (JsonApiDocument, JsonApiErrors, assertJsonApiSpecCompliant) in your own test suite (^12.0).

MIT

• Gregory Haddow
• Woohoo Labs and contributors

• rest
• api
• psr-7
• jsonapi
• JSON-API
• psr-15

Published on Packagist.org on 2026-07-13 08:07 UTC

README

A modern, server-side JSON:API 1.1 library for PHP 8.3+.

Part of the jsonapi.rest suite — a complete, spec-compliant JSON:API 1.1 stack for PHP: this framework-agnostic core, a Symfony bundle, a Laravel package, and a typed TypeScript client, bound together by one conformance-tested OpenAPI 3.1 contract.

haddowg/json-api is a typed, framework-agnostic toolkit for building JSON:API 1.1 compliant APIs in modern PHP — serialising resources, parsing and validating requests, negotiating content, and shaping responses exactly as the specification requires, without tying you to any particular framework or data layer.

The design leans on contemporary PHP: readonly value objects, enums, a typed exception hierarchy, PSR-7 v2 and PSR-15 throughout, and a fluent schema layer for declaring a resource type's attributes, relationships, filters, sorts, and validation in one place. First-class support for JSON:API profiles is built in rather than bolted on.

Requirements

• PHP 8.3, 8.4, or 8.5

Installation

composer require haddowg/json-api

Documentation

The full documentation is published at haddowg.github.io/json-api. Start with Getting started for an end-to-end walkthrough, or browse the documentation index for the reference pages.

Using a framework? The Symfony bundle and Laravel package wrap this core with idiomatic routing, validation, and a reference data layer.

Try it

The worked music-catalog example serves itself — run docker compose up in examples/music-catalog/ and browse the live API at http://localhost:8080/albums. It is also the single source of truth for every documentation snippet.

Contributing

See CONTRIBUTING.md. This project uses Conventional Commits and automated releases via release-please.

Credits

This package began as a derivative work based on woohoolabs/yin, and substantial portions of the codebase derive from it — sincere thanks to Woohoo Labs and the yin contributors for the original library. The fluent schema layer draws inspiration from Laravel JSON:API, whose schema-first developer experience shaped this project's recommended API.

Licence

Released under the MIT Licence, with dual copyright held by Gregory Haddow and Woohoo Labs and contributors (the original woohoolabs/yin authors).