What is the relationship between OAS extensions and overlays?

[kinlane]

As TSC is jumpstarting the overlay conversation again, I'd like to hear the communities thoughts about the relationship between OAS extensions and overlays. I have my own view of this, and have learned from others in the community about some of the top overlay use cases might, and think more about how the current OAS extension world might influence or inform the overlay conversation.

After looking through the extension of 16 different API service providers I identified the following ways in which folks are extending the spec:

• Documentation - Expanding on the spec for publishing documentation.
• Examples - Enriching the examples for each API for use across the API lifecycle.
• Parameters - Providing more details about each of the path, header, or question parameters.
• Parameter Groups - Helping group parameters to help make them more organized.
• Defaults - Offering up a set of default values for different layers of an OpenAPI.
• Enumerators - Adding more information about enumeration for properties and parameters.
• Versioning - Allowing there to be more details about the versioning of each API or schema.
• Role Based Access Control (RBAC) - Adding a layer for RBAC across an API and their surface area.
• TLS - Providing details about the transport level security being applied to each API.
• Compression - Outlining the type of compression that is available as part of each API.
• Validation - Describing the validation that occurs when an API is consumed or tested.
• Authentication - Expanding on the overall authentication and access management.
• Basic Auth - Providing more detail about Basic Auth that OpenAPI doesn’t provide.
• API Key - Providing more detail about an API key that OpenAPI doesn’t provide.
• OAuth - Providing more detail about oAuth that OpenAPI doesn’t provide.
• JWT - Providing more detail about JWT that OpenAPI doesn’t provide.
• Environments - Adding additional details about development, production or other environment.
• Management - Defining the management layer that is in place for each API.
• Policy - Allowing policies to be applied to each API being defined by OpenAPI
• Rate Limit - Defining what levels of consumption are available for each API
• Throttling Tier - Further defining the overall access or throttling tiers available.
• Configuration - Providing configuration for how an API should be operating.
• Gateway Request - Additional information regarding the request surface of an API.
• Gateway Response - Additional information regarding the response surface of an API.
• Integrations - Detailed information about the integration with another API behind an API.
• Backend - Further details about backend integrations and connections behind each API.
• Dependencies - Machine readability details about all of the dependencies an API has.
• Languages - Machine readable information about the language available for an API.
• CORS - Details about how cross origin resource sharing is addressed for an API.
• Code Samples - Providing samples or snippets for all available API paths.
• Client Code Generation - Information regarding what client side code generation.
• Server Code Generation - Information regarding what server side code generation.
• Requests Scripts - Defining scripts that are executed with each API request made.
• Responses Scripts - Defining scripts that are executed after each API response.
• Translation - Details about what translation occurs as part of each API request or response.
• Filtering - Information regarding what filtering is available or applied to each API request or response.
• Aliases - Providing details regarding aliases for different elements of each API.
• Pagination - Offering more structure regarding the pagination of API resources.
• Triggers - Defining what triggers are available or executed as part of API operations.
• Notifications - Outlining available notifications that are made when an API is executed.
• URL Encoding - Providing more details about how a URL is encoded as part of each API resource.
• Data Store - Associating a data store with each API being defined as an OpenAPI.
• Caching - Adding information regarding how each API is being cached as part of operations.
• Security - Further expanding on how security is handled when it comes to each API operations.
• Import - Providing additional information that needs to be considered or applied upon OpenAPI import.
• Export - Providing additional information that needs to be considered or applied upon OpenAPI export.
• Audiences - Offering more detail about the audience an API is intended for as part of each OpenAPI.
• Capabilities - Having a machine readable defining of what each API is capable of doing.
• Traits - Further outlining the traits of each of the APIs, helping further flesh out what each one does.
• Tags - Adding more rich detail beyond the base tagging provided by OpenAPI.
• Tag Groups - Helping group tags, adding another layer of organization to each API.

I am just curious to more clearly define what use cases are best addressed through extensions, and which might be better suited for overlays. Then work to define a whole catalog of use cases to help drive the overlays conversation.

[darrelmiller]

One class of scenarios that makes sense for Overlays are those where there are a set of extensions that are cohesive for some reason.
e.g.

• Additional information to drive client generation
• Policies for API Management proxies
• Localization data

Overlays are additionally useful when there are multiple sets of cohesive extensions. e.g. translations in multiple languages.

Overlays are useful when trying to reduce the complexity/bulk of the core API description, especially if the information in the overlay is only used in certain scenarios.

[handrews]

I'm assuming this was answered well enough given the lack of further discussion. If more discussion is desired, I'd suggest opening it at the OAI/Overlay-Specification repository.