Json Schema Laravel Package

Product Decisions This Supports

• API Documentation & Self-Service Developer Portals: Automatically generate and maintain JSON Schema definitions for API resources, reducing manual documentation effort and ensuring consistency between code and API specs. This aligns with initiatives to improve developer experience (DX) and reduce onboarding friction for third-party integrations.
• Contract-First Development: Enable a contract-first approach by deriving schemas from PHP classes, ensuring API contracts are always in sync with backend logic. Supports roadmap items focused on reducing API drift and improving reliability.
• Build vs. Buy: Avoid building custom schema generation tools or relying on external tools (e.g., Swagger/OpenAPI generators) that may introduce latency or dependency risks. This package offers a lightweight, PHP-native solution.
• Validation & Testing: Use generated schemas for runtime validation (e.g., via API Platform’s built-in validation) or to power automated testing (e.g., validating payloads against schemas in CI/CD pipelines).
• Multi-Format API Support: If your product offers APIs in multiple formats (GraphQL, REST, gRPC), this package can serve as a single source of truth for request/response schemas, reducing duplication.
• Compliance & Governance: Generate schemas for auditing, compliance (e.g., GDPR data models), or internal governance tools (e.g., tracking API usage patterns).

When to Consider This Package

• Adopt when:

  • You’re using API Platform or a similar PHP framework that relies on metadata-driven APIs (e.g., Symfony, Doctrine).
  • Your team prioritizes developer velocity over custom tooling; this reduces boilerplate for schema maintenance.
  • You need real-time schema generation (e.g., for dynamic APIs where classes change frequently).
  • Your API contracts are PHP-class-centric (e.g., DTOs, entities) and don’t require complex OpenAPI/Swagger extensions.
  • You’re already invested in JSON Schema for validation, testing, or third-party tooling (e.g., Postman, Stoplight).

• Look elsewhere when:

  • Your API is not PHP-based (e.g., Node.js, Go, Python). Use native tools like jsonschema (Python) or gojsonschema.
  • You need OpenAPI/Swagger 3.0+ with advanced features (e.g., security schemes, examples, or server URLs). Consider nelmio/api-doc-bundle or zircote/swagger-php.
  • Your schemas require runtime customization (e.g., conditional fields, dynamic properties). This package is read-only; pair it with a templating engine or use a more flexible tool.
  • You’re building a public API portal with interactive docs (e.g., Swagger UI). Combine this with an OpenAPI generator for better UX.
  • Your team lacks PHP expertise. Evaluate the maintenance overhead of integrating a niche package.

How to Pitch It (Stakeholders)

For Executives/Business Leaders:

"This package lets us automate the generation of JSON Schema definitions directly from our PHP classes, cutting the time we spend manually documenting APIs by 50%. For example, if we’re adding a new endpoint for [Feature X], the schema for its request/response payloads will auto-update—no more out-of-sync docs. This reduces integration errors for partners, speeds up developer onboarding, and aligns with our goal to [reduce API support costs/increase adoption]. It’s a lightweight, low-risk way to future-proof our API contracts, especially as we scale [Y feature]."

Key Outcomes:

• Faster API iterations (no manual schema updates).
• Reduced technical debt in documentation.
• Stronger compliance/governance for API usage.

For Engineering Teams:

*"This is a drop-in solution for API Platform projects that generates JSON Schema from your PHP classes (e.g., DTOs, entities). Here’s why it’s worth adopting:

• Zero Boilerplate: No need to maintain separate schema files or annotations. Schemas are derived from your existing code.
• Validation Integration: Works seamlessly with API Platform’s built-in validation (e.g., @Assert\ constraints).
• Testing: Use the generated schemas to validate payloads in unit/integration tests (e.g., with webonyx/graphql-php or custom assertions).
• Lightweight: MIT-licensed, no external dependencies, and actively maintained (28 stars, recent commits).

Trade-offs:

• Not a full OpenAPI generator (no Swagger UI or advanced features).
• Best for PHP-centric workflows; pair with other tools for public docs.

Proposal: Let’s pilot this for [Module A] and measure the reduction in schema maintenance time. If successful, we can roll it out to all API resources."*

Call to Action:

• "Can we add this to our [next sprint] as a proof of concept?"
• "Should we pair this with [OpenAPI tool] for public docs?"