Skip to content

Latest commit

 

History

History
48 lines (34 loc) · 7.45 KB

SPECIAL_INTEREST_GROUPS.md

File metadata and controls

48 lines (34 loc) · 7.45 KB
Raw

OpenAPI Initiative - Special Interest Groups

Overview

This is an overview of the Special Interest Groups (SIG) created within the OpenAPI Initiative (OAI), working to provide a simple overview of what SIGs are, how they operate, and how they can contribute to moving forward the conversation around the OpenAPI Specification (OAS) and wider API landscape.

Currently, there are two types of SIGs that have emerged to move forward some aspect of using OAS.

  • The first one being about establishing and developing specific extensions to OAS, with some eventually becoming a formal part of the specification, or remaining as an extension, or overlay to the spec, or possibly as an independent specification.
  • The second type of SIG is more focused on the usage of OAS in service of a specific industry, which may eventually contribute changes, extensions, or overlays to OAS, but will be more likely about coordination across OAS usage within specific industry.

List of Special Interest Groups

SIG Description Type Repo Slack
Overlays SIG focused on defining the overlays specification for OAS Technical focus repo slack
Security SIG focused on moving forward security portions of the specification Technical focus repo slack
Workflows SIG focused on building workflows with multiple APIs using OAS Technical focus repo slack
Service Level Agreement SIG focused on the SLA extension being developed Technical focus repo
Codegen SIG focused on moving forward the code generation from specifications Technical focus slack
Formats focused on the formats registry effort Technical focus repo
Lifecycle focused on defining the API lifecycle around an API being developed using OAS Technical focus repo slack
Travel SIG focused on using OAS within the travel industry Industry focus repo slack
Finance SIG focused on using OAS within the finance industry Industry focus repo
Moonwalk Focused on creating the next major version of OpenAPI Technical focus repo slack

SIG Building Blocks

These are some of the commonly recommended building blocks to help move each SIG forward in a standardized way, helping provide a common blueprint that SiGs can employ to move forward each conversation and encourage participation within the OAS community.

  • Champion - Each SIG should have at least one, but ideally two champions who will help lead each SIG, and act as the owner of each group, and support discussions.
  • Title - The title of your SIG, providing a simple title that reflects its purpose.
  • Description - A brief description, ideally a single paragraph that describes your SIG.
  • Statement of Work - A detailed statement of work (SOW) defining what your SIG will accomplish.
  • Github Repository - It is recommended that each SIG should have its own Github Repository, providing a README, issues, projects, discussions, and other solutions for managing work. - Request Github Repo within Spec Slack channel.
  • Agenda - It is recommended that SIGs utilize Github Issues to manage the regular agenda in a similar way as done with the TDC meetings to move forward the core specification.
  • Slack Channel - It is recommended that each SIG have its own Slack Channel, providing an asynchronous place to engage in discussion, with emphasis on the public discussion via public Github discussions.
  • Recurring Meeting - It is common for SIGs to have a weekly or bi-weekly meeting using Zoom or Google Meet, providing a regular time in which SIGs will convene to move the conversation forward.

None of these are required but should provide a set of common practices to consider. If there are other requirements like calendar, document management, and other building blocks in use, please let us know so that we can add to this list and inform each of the existing SIGs, as well as new ones.

OpenAPI Initiative SIG Structure and Process

It was decided in May of 2021 to go with a less formal approach to starting up and operating SIGs to encourage their formation and evolution. The OAI depends on each group champion and leader to define and manage each SIG and contribute to existing OAI projects, groups, and discussions. There is no formal OAI structure or process for how SIGs should operate, with this document being just one attempt at documenting what is currently happening.

This description contained in this ReadMe, Issue 21, as well as the supporting Kanban board is an attempt to continue formalizing and communicating the structure and process for SIGs but does not claim to be the formal process, or is comprehensive.

Like most aspects of the OAI, SIGs are dependent on champions to move things forward and help define what SIGs are and how they add value to OAS and the community. Please share your feedback, corrections, additions, and concerns below, and feel free to add to the project Kanban board, update your SIG's information, or start up a new SIG to move forward with something that matters to you. SIGs reflect a pretty compelling opportunity to move OAS and the OAI community forward in different ways, beyond the core specification development, and marketing activities that have been going on since the forming of the OAI. We look forward to what your SIG can do, and encourage your participation in helping push forward the SIG discussion within the OAI and OAS community.