refactor(jsonapi): single source of truth for the attribute/relationship split#8325
Merged
soyuka merged 1 commit intoJun 17, 2026
Merged
Conversation
soyuka
force-pushed
the
feat/jsonapi-jsonschema-single-source
branch
from
d62473c to
7868d0d
Compare
…hip split `SchemaFactory::getRelationship()` recomputed the attributes-vs-relationships partition from `getNativeType()`/`getBuiltinTypes()` — a near-verbatim copy of the runtime split in `ItemNormalizer::getComponents()`. The two implementations could drift on any change (collection handling, union/intersection types, a TypeInfo migration), the root mechanism behind the api-platform#8308 class of bugs. Extract the split into a shared `ResourceLinkageResolver` (both the legacy `getBuiltinTypes` and modern `getNativeType` paths) consumed by both the normalizer (runtime) and the JSON Schema factory (doc-time), so they cannot diverge. As a result, also map reserved attribute names through `ReservedAttributeNameConverter::JSON_API_RESERVED_ATTRIBUTES` in the schema instead of hard-coding `id` -> `_id`: a scalar property named `type`/`links`/ `relationships`/`included` is now documented under the same prefixed key the response emits (same doc/response mismatch as api-platform#8308, for four of five names). Refs api-platform#8322, api-platform#8313, api-platform#8308
soyuka
force-pushed
the
feat/jsonapi-jsonschema-single-source
branch
from
7868d0d to
b9f6fb9
Compare
soyuka
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #8313 / #8321, surfaced while reviewing #8313.
Single source of truth for the attributes/relationships split
SchemaFactory::getRelationship()recomputed the attributes-vs-relationships partition fromgetNativeType()/getBuiltinTypes()— a near-verbatim copy of the runtime split inItemNormalizer::getComponents(). The two implementations could drift on any change (collection handling, union/intersection types, a TypeInfo migration) — the root mechanism behind the whole #8308 class of bugs.Extracted into a shared
ResourceLinkageResolver(@internal, both the legacygetBuiltinTypesand moderngetNativeTypepaths) consumed by both the normalizer (runtime) and the JSON Schema factory (doc-time), so they cannot diverge. ~150 lines of duplicated logic removed.Reserved attribute names (falls out of the unification)
The schema generator special-cased only
id→_id, while the runtimeReservedAttributeNameConverterprefixes five names:id,type,links,relationships,included. A scalar property namedtype/links/relationships/includedwas documented under the bare key but emitted prefixed (_type, …) — the same doc/response mismatch as #8308, for four of the five names. Attribute and relationship keys are now mapped throughReservedAttributeNameConverter::JSON_API_RESERVED_ATTRIBUTES(single source of truth).Notes
ResourceLinkageResolveris an optional last constructor argument on both classes, default-constructed from theResourceClassResolverthey already hold; Laravel's manual wiring keeps working unchanged.api_platform.jsonapi.resource_linkage_resolverin the Symfony bundle.#/definitions/<Class>definition and the unreset\$builtSchemafactory state.Tests
ResourceLinkageResolverTest— split classification (scalar, to-one, nullable to-one, to-many, non-resource object, no type).ReservedAttributeNameSchemaFactoryTest— all five reserved names documented under the prefixed key.