Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Gracefully handle property incompatibilities during an update

Aperta
  • Qualcosa non va?
#299 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Tranquilla
Stack tecnologico
openapi
Ambito
documentation

Direzione di ricerca

Inizia con le regole di fusione ricorsiva e gli esempi upstream.yaml/fix.yaml nell’issue. Esamina come l’Overlay Specification definisce attualmente i valori incompatibili di target e update/copy, quindi determina la formulazione normativa necessaria per il comportamento di sostituzione. Il lavoro è completato quando la specifica risolve chiaramente l’esempio scalar-to-array senza richiedere un’azione remove separata.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.
Lingua principale
JavaScript
Stelle
121
Fork
38
Merge medio
1g 17h
PR unite (30g)
9

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di OAI/Overlay-Specification

Tutte le issue di OAI/Overlay-Specification

Issue simili

Altre issue su JavaScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.