Download the PHP package zeusi/json-schema-extractor without Composer

JSON Schema Extractor

JSON Schema Extractor generates JSON Schema documents from PHP DTOs by extracting native types, PHPDoc, validation constraints, and serialization metadata through a modular pipeline.

Typical use cases include:

• structured output definitions for LLMs
• reusable DTO schemas for a broader AsyncAPI documentation flow

Features

• No mandatory dependencies: install only the optional packages needed by the components you enable.
• Existing metadata first: builds schemas from native PHP types, PHPDoc, Symfony Validator, and serializer metadata without requiring schema-specific attributes.
• PHPDoc-aware enrichment: reads PHPDoc through the PHPStan or phpDocumentor based enrichers, covering generics, shaped arrays, literals, ranges, enums, nullable types, and text metadata.
• Symfony integration: maps supported Symfony Validator constraints and projects output shapes through Symfony Serializer metadata such as groups, serialized names, name converters, discriminators, and known normalizers.
• Reference-safe object graphs: handles nested DTOs, reusable definitions, enums, and circular references through $ref.
• Serialization-aware output: separates the PHP model from the JSON-facing shape, with built-in strategies for PHP json_encode() and Symfony Serializer.

Installation

The core package has no mandatory dependencies. Some components need optional packages depending on the metadata source you want to use:

Install only the packages needed by the discoverers, enrichers, or serialization strategies you enable.

Quick Example

Given a small DTO:

Create an extractor:

The resulting schema includes native PHP types from reflection and PHPDoc information read by the enabled enricher, such as list item types and shaped array fields:

For executable examples, see bin/schema.php.

Architecture

Extraction is intentionally split into separate phases:

1. Discover the PHP class model
2. Enrich that PHP model with metadata from PHPDoc, attributes, validators, or custom sources
3. Project the enriched PHP model into the serialized output shape
4. Map the serialized output shape to JSON Schema

When instantiating SchemaExtractor, choose components according to the metadata you trust and the serializer you actually use at runtime.

Custom behavior can be added by implementing a discoverer, enricher, serialization strategy, or mapper.

Symfony Bundle

The Symfony bundle registers the built-in components as services. It reduces the boilerplate needed to define extractor pipelines, especially when using Symfony Serializer and Symfony Validator services. Each extractor must explicitly choose the serialization strategy that matches the JSON produced by the application.

See docs/symfony-bundle.md for bundle configuration and available Symfony integration details.

Components

Discoverer

ReflectionDiscoverer is the default and currently only discoverer. It creates the baseline PHP model by reading class properties and native PHP types through reflection, optionally using the class short name as the schema title.

To create a custom discoverer implement DiscovererInterface.

Enrichers

Enrichers mutate the PHP model before serialization projection. They should merge information where possible and avoid overwriting stronger information with weaker inferred metadata. They run sequentially, so their order can still matter when two enrichers write to the same part of the model.

For a side-by-side capability matrix of the two PHPDoc enrichers, see docs/enrichers/phpdoc-enricher-comparison.md.

To create a custom enricher implement EnricherInterface.

Serialization Strategies

Serialization strategies convert the enriched PHP model into the JSON-facing payload consumed by the mapper. They are the right place for output field names, omitted fields, discriminator fields, root payload changes, and serializer-specific normalized types.

To create a custom serialization strategy implement SerializationStrategyInterface.

Mapper

StandardJsonSchemaMapper is the default and currently only mapper. It converts the serialized payload model to JSON Schema. By default, class-backed DTOs and enums are collected in reusable definitions and referenced with $ref. The emitted definition keyword follows the configured dialect: definitions for Draft-7 and $defs for Draft 2020-12.

Nested objects and complex structures are handled recursively. With ClassReferenceStrategy::Definitions, class-backed types are emitted once as reusable definitions and reused through $ref. Circular references are always broken with $ref.

Mapper-level schema policy is configured through StandardJsonSchemaMapperOptions:

The default dialect is Draft-7 and the root $schema keyword is omitted unless includeSchemaKeyword is enabled. If you prefer class-backed schemas to be expanded at the usage site, use ClassReferenceStrategy::Inline.

To create a custom mapper implement JsonSchemaMapperInterface.

Schema Semantics

additionalProperties

Class-based object schemas are strict by default: SchemaExtractorOptions defaults to additionalProperties: false. This is meant to make DTO-shaped schemas describe the known serialized payload, not an open-ended object.

You can override that default per class with #[AdditionalProperties(true)]. Inline object shapes can also carry their own additionalProperties value, for example shaped dictionaries or Symfony Validator Collection constraints.

Dictionary-style PHPDoc types such as array<string, T> are represented as JSON objects whose additionalProperties value is the schema for T.

required

required means that a field is expected to be present in the serialized payload. It does not mean that the field value cannot be null. The extractor does not infer required from PHP non-nullable types alone; enrichers and serialization strategies can mark fields as required or optional when their metadata describes payload presence.

Limitations

• Interfaces and abstract/base classes need an explicit strategy, such as Symfony discriminator metadata, to identify possible concrete output shapes
• Some JSON Schema decisions are necessarily conservative. For example, unions are collapsed when safe, but oneOf versus anyOf cannot always be inferred from PHP types alone

License

This project is licensed under the MIT License. See the LICENSE file for details.