Json Ld Api Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for API surface: This is the open-source, MIT-licensed server component behind API Platform — the dunglas/json-ld-api-bundle name in the dependency graph is the historical/legacy artifact; the maintained codebase is api-platform/core (now on the 5.x line). It replaces weeks of hand-written controllers, serializers, pagination, filtering, and link-building with declarative resource metadata — a clear "buy" for teams needing standards-compliant APIs rather than bespoke endpoints.
• Feature bets on standards-first APIs: Choosing it commits the product to JSON-LD / Hydra hypermedia, auto-generated OpenAPI/JSON Schema, and GraphQL from the same model. That is a roadmap decision: interoperable clients, discoverable APIs, and generated SDKs come "for free," but the API contract becomes shaped by the framework's conventions.
• Use cases it unlocks: headless/mobile backends over existing Eloquent models, partner or B2B integrations that expect schema.org-vocabulary payloads (good for SEO/linked-data), internal data products, and rapid CRUD-plus-GraphQL prototyping to validate a market before investing in custom infrastructure.
• Velocity vs. differentiation: It accelerates undifferentiated plumbing (docs, validation wiring, filters, pagination, content negotiation), freeing the team to spend effort on domain logic — but only if the domain maps cleanly onto resource + provider/processor abstractions.
• Governance and DX investment: Auto-generated OpenAPI and consistent error/hydra semantics give PMs a lever for API style guides, versioning discipline, and client-team onboarding without a bespoke platform team. Recent releases keep tightening error semantics (e.g. consistent 422 responses for empty scalar parameters and backed-enum validation failures), which is exactly the kind of contract stability client teams depend on.
• Contract stability as a trackable metric: The 5.0.x line is shipping fixes rather than contract changes — metadata precedence rules, JSON Schema correctness for nested resources/DTOs/intersection types, and Doctrine filtering/ordering behavior. For a PM this means "adopt now, expect correction not redesign," which is a low-risk window to commit a roadmap.

When to Consider This Package

• Adopt when: the team is already on Laravel or Symfony with PHP 8+, the product is fundamentally resource-oriented (CRUD with relations), and you need hypermedia, GraphQL, and OpenAPI concurrently with a small team.
• Adopt when: standards compliance (JSON-LD, schema.org) is a product requirement, not a nice-to-have — e.g. discoverability, federated data, or partner contracts.
• Adopt when: you value an actively released, strict-backward-compatibility upstream with conventional commits and a large contributor base; that lowers long-term maintenance risk. The 5.0.x cadence is dominated by targeted fixes with new contributors arriving each release — a healthy maintenance signal.
• Adopt when: you want validation semantics that behave predictably across REST and GraphQL — recent work on parameter/operation precedence, GroupSequence support, and 422 error consistency reduces the "why does this endpoint return 400 vs 422" class of support tickets.
• Look elsewhere when: you only need a plain REST CRUD API — Laravel API Resources or hand-rolled controllers are cheaper to learn and debug, and avoid the metadata/attribute layer.
• Look elsewhere when: the product is RPC-style or heavily custom business logic per endpoint; the declarative model becomes fighting the framework.
• Laravel-specific diligence required: the codebase and its contributor guidance remain Symfony-monorepo-centric (console fixtures, component linking, Doctrine fixtures). Laravel support is real and actively patched (e.g. nullable optional belongsTo handling, relation test coverage), but parity with Symfony across GraphQL and certain hypermedia features must be verified against your exact version before committing a roadmap to it.
• Packaging caveat: pin and verify against api-platform/core 5.0.4 or later plus the matching Laravel integration package; treat the old bundle name as a legacy alias. Budget explicitly for the 5.x major-version migration and for future majors — upgrades are a recurring cost of ownership, not a one-off.

How to Pitch It (Stakeholders)

To executives: This is a mature, MIT-licensed framework component with a large community that turns our existing data models into standards-compliant REST/JSON-LD and GraphQL APIs in days rather than sprints. It reduces time-to-market for any API-first initiative, generates documentation and client SDKs automatically, and avoids vendor lock-in because the contracts are open standards (JSON-LD, OpenAPI, GraphQL) rather than proprietary formats. Upstream is in a steady patch cadence with no contract-breaking changes in the current line, which makes this a safe moment to commit.

To engineering: Declarative resource metadata replaces boilerplate controllers; state providers/processors give clean extension points; OpenAPI, validation, filtering, and pagination are built in. Upstream enforces backward compatibility, conventional commits, and a test-first contribution culture — signals of a maintainable dependency. Recent releases show the metadata and JSON Schema layers being actively hardened (nested resources, DTOs, intersection types, with*() immutability, parameter-vs-filter precedence) and Laravel-specific defects being closed, so early Laravel parity risks are shrinking rather than accumulating. We should still validate Laravel parity and version pinning up front, and plan for major-version upgrade effort as an ongoing cost of ownership.

Risks to acknowledge: residual Laravel feature parity gaps vs. Symfony; legacy package naming causing install confusion; and the discipline required to keep API contracts stable once clients depend on generated hypermedia and schemas. The high volume of metadata and serialization fixes in patch releases also means we should pin minor versions deliberately and re-run contract tests on upgrade rather than floating to latest.