OpenAPI-Specification icon indicating copy to clipboard operation
OpenAPI-Specification copied to clipboard

Published 20 hours ago • verified publisher icon OAI

Provide guidance on using OAS with Overlay and Arazzo

Open handrews opened this issue 1 year ago • 2 comments
trafficstars

Many long-requested features for OAS can now be better handled by using the Overlay and/or Arazzo specifications.

I think Arazzo mostly overlaps with the Link Object, but I might be wrong there. Some guidance as to when to use which would probably be good to add.

Overlays solve many requests for global or default values, and if it is reasonably straightforward to do that, we should include info in the OAS pointing to the Overlay spec for that use case. Other use cases include various reference-and-modify constructs (hmm.. do we want to consider pushing this instead of the adjacent-fields-in-Reference-Object approach?)

Putting this in the next patch release, although there may be additional things to do in minor releases here.

handrews avatar Nov 21 '24 21:11 handrews

I think Overlay usage is a great target for the many language localization requests over the years.

jeremyfiel avatar Nov 26 '24 02:11 jeremyfiel

@handrews did you have a specification change in mind for this issue? I'm not sure I know how to "do" what you are asking, can you say a bit more about what's expected?

lornajane avatar May 15 '25 19:05 lornajane

@lornajane sorry I missed this question before. I've brought this up again in my 3.3+ proposals in #5116.

For Overlays, the main OAS spec change is to indicate that an Overlay is a solution to a problem that people expect to be solved in the OAS. This requires deciding what belongs in Overlays and therefore will not be added to the OAS.

Here is a list of things we have told people that they should use Overlays for, or at least toyed with the idea. This doesn't mean that every one of these needs mentioning in the OAS, but at least the general categories should be. Far more people read the OAS than know about Overlays, let's give ourselves some free visibility!

I did not make an effort to filter out dups.

  • Multiple languages / I18N / L10N (note there was a fair bit of pushback here))
    • #274
    • #1740
  • Filtering
    • #433
    • #569
  • Globals / Defaults
    • #521
    • #563
    • #690
    • #1577
    • #1652
    • #2357
    • #4992
    • #5006
  • Grouping, copying, and re-use
    • #1364
    • #1794
    • #2298
    • #2668
    • #2871
    • #3293
    • #4231
  • Managing large descriptions (when externalDocs is not available)
    • #1570
  • Non-object re-use
    • #1741
    • #3902
    • #4211
  • Differing deployment servers and/or security
    • #2322
    • #2628

handrews avatar Nov 12 '25 04:11 handrews