Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

JSON Schema: possible incompatibilities when plugging symfony/json-schema

Đang mở
  • Có gì không ổn?
#8,697 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
8/100
Loại issue
Tái cấu trúc
Độ rõ ràng
Cần làm rõ
Mức độ hoạt động
Sôi nổi
Công nghệ
php
Lĩnh vực
api

Hướng nghiên cứu

This is a design survey, not a single fix. Start with ShortNameDefinitionPolicy, DefinitionPolicyInterface, SchemaDocument and DefinitionProcessorInterface, which the issue names as the points where the output would diverge. Done means agreeing which differences API Platform will accept, which it will adapt through an extension point, and which need follow-up issues, with the decision recorded on this thread.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

Description

Follow-up of #8696: what changes if api-platform/json-schema uses symfony/json-schema (https://github.com/symfony/symfony/pull/66685).

1. Dependency constraints

  • The component first ships in Symfony 8.2 (its CHANGELOG.md).
  • It requires PHP >=8.4.1, API Platform requires PHP >=8.2.
  • It requires symfony/type-info ^7.4.6|^8.0.6, API Platform requires ^7.4 || ^8.0.

2. Output changes with the default configuration

  • JSON Schema output uses $defs and #/$defs/ instead of definitions and #/definitions/ (Dialect::jsonSchema202012()). OpenAPI output keeps #/components/schemas/.
  • $schema is https://json-schema.org/draft/2020-12/schema instead of http://json-schema.org/draft-07/schema#.
  • There is no Swagger 2.0 dialect. API Platform still has the deprecated --spec-version=2 export.
  • Definition names (ShortNameDefinitionPolicy) put the format in a format.<format> part instead of a .jsonld suffix, append the direction (input/output), and have no .partial, .jsonMergePatch or _noid suffix. Example: Dummy-read_format.jsonld_output instead of Dummy.jsonld-read. A custom DefinitionPolicyInterface can produce other names.
  • With a direction, write-only properties are removed from output schemas and read-only properties from input schemas. API Platform keeps them, flagged readOnly/writeOnly. The component only emits these flags without a direction.
  • Output schemas require properties that are always initialized (default value, promoted or constructor-set). Otherwise, mandatory constructor arguments are required. API Platform uses ApiProperty::isRequired() (validation metadata or explicit required), with no required for partial updates.
  • callable and resource properties are removed. API Platform describes them as type: string.
  • Examples are examples: [value] on JSON Schema 2020-12 and OpenAPI 3.1, and example only on OpenAPI 3.0 (Dialect::example()). API Platform emits example.
  • Descriptions come from the PHPDoc. Values API Platform takes from metadata (ApiProperty description, deprecated, externalDocs from types, operation description) are not produced.
  • Ramsey UuidInterface is not handled. API Platform describes it as format: uuid.

3. Extension points

  • The extension signatures have no operation or ApiProperty. API Platform data has to go through Configuration::$context, which is neither part of the definition fingerprint nor of the default name. Any shape that depends on it (operation, partial update, gen_id) must be encoded in the name by a custom policy, or two shapes share one definition.
  • SchemaDocument::reserve() and define() are @internal, and a DefinitionProcessorInterface can only change the definition it receives. Shared definitions such as HydraItemBaseSchema cannot be registered from an extension.
  • The root collection schema is not passed to any extension, so hydra:member, JSON:API data/links/meta and HAL _embedded stay in an outer decorator.
  • A PropertySchemaProviderInterface can return user-defined schemas (ApiProperty schema, jsonSchemaContext, openapiContext), but enrichers still run on top. API Platform leaves user-defined schemas untouched.
  • A definition is built for the first occurrence of a name, so shapes depending on the parent property (e.g. gen_id on an embedded relation) collide: "a difference coming only from the parent cannot be detected and the first occurrence wins" (DefinitionPolicyInterface).
  • A SchemaDocument throws when used with another refPath, so JSON Schema (#/$defs/) and OpenAPI (#/components/schemas/) output cannot share one document.
Fits the existing extension points
  • IRI references for non-embedded relations: ClassSchemaResolverInterface with DefinitionParent.
  • Definition names: DefinitionPolicyInterface.
  • Input/output DTOs: caller side.
  • Validator constraints: built-in ValidatorPropertySchemaEnricher.
  • Definitions shared across OpenAPI operations: SchemaDocument, Dialect::openApi30()/openApi31().
  • Eloquent models: the generator takes a PropertyInfoExtractorInterface.
Ngôn ngữ chính
PHP
Star
2.6k
Fork
989
Merge trung bình
2 ngày 1 giờ
Pull request đã merge (30 ngày)
104

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của api-platform/core

Tất cả issue của api-platform/core

Issue tương tự

Thêm issue về PHP

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.