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

Gracefully handle property incompatibilities during an update

Đang mở
  • Có gì không ổn?
#299 2 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
35/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Ít trao đổi
Công nghệ
openapi
Lĩnh vực
documentation

Hướng nghiên cứu

Bắt đầu với các quy tắc hợp nhất đệ quy và các ví dụ upstream.yaml/fix.yaml trong issue. Xem xét cách Overlay Specification hiện định nghĩa các giá trị target và update/copy không tương thích, sau đó xác định cách diễn đạt mang tính quy phạm cần thiết cho hành vi thay thế. Công việc được xem là hoàn tất khi specification giải quyết rõ ràng ví dụ scalar-to-array mà không yêu cầu một hành động remove riêng biệt.

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

Mô tả

Scenario: You have a broken upstream OpenAPI spec you don't control, and you're using an overlay to fix it.

Here's a minimal example. The upstream spec has a type: string property in a response body:

# upstream.yaml
openapi: 3.1.0
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets:
    get:
      operationId: listPets
      responses:
        '200':
          description: A list of pets
          content:
            application/json:
              schema:
                type: object
                properties:
                  tag:
                    type: string
                    example: "indoor"

However when we try the API, we realize that tag is actually an array instead of a scalar string and the upstream OAS was incorrect. Natural overlay to fix it:

# fix.yaml
overlay: 1.0.0
info:
  title: Fix broken tag
actions:
  - target: $.paths['/pets'].get.responses['200'].content['application/json'].schema.properties.tag
    update:
      type: array
      items:
        type: string
      example:
        - "indoor"

When the overlay engine recursively merges the update object into the tag property, it eventually reaches the example key. The target value is a YAML scalar ("indoor") and the update value is a YAML sequence (["indoor"]). Per the spec:

Other property value combinations are incompatible and result in an error.

So this is an error condition — you can't fix a wrongly-typed field with a simple update: it's got to be removed and re-added.

The only way to fix the above scenario becomes:

overlay: 1.0.0
info:
  title: Fix broken tag
actions:
  - target: $.paths['/pets'].get.responses['200'].content['application/json'].schema.properties.tag.example
    remove: true
  - target: $.paths['/pets'].get.responses['200'].content['application/json'].schema.properties.tag
    update:
      type: array
      items:
        type: string
      example:
        - "indoor"

Which works but is both overly verbose and brittle because all incompatible fields have to be dropped from the target to be able to overlay without an error.

In my mind it might make more sense if the specification was a little more graceful here, specifically with regards to recursive merging behaviour (I.e. I think an error when the target and update/copy are incompatible is the right thing). Currently:

If a property exists in both update or copy and target object:

  • A primitive value of the update or copy property replaces a primitive value of the target property.
  • An array value of the update or copy property is concatenated with an array value of the target property.
  • An object value of the update or copy property is recursively merged with an object value of the target property.
  • Other property value combinations are incompatible and result in an error.

Would become:

If a property exists in both update or copy and target object:

  • An array value of the update or copy property is concatenated with an array value of the target property.
  • An object value of the update or copy property is recursively merged with an object value of the target property.
  • Otherwise the property value of the update or copy property replaces the value of the target property.
Ngôn ngữ chính
JavaScript
Star
123
Fork
38
Merge trung bình
3 ngày 22 giờ
Pull request đã merge (30 ngày)
11

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 OAI/Overlay-Specification

Tất cả issue của OAI/Overlay-Specification

Issue tương tự

Thêm issue về JavaScript

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.