OAI Special Interest Group (SIG) Overview

[kinlane]

Overview

This is an overview of the Special Interest Groups (SIG) that have been emerging 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). Providing an evolvable document that can help OAI members establish new SIGs, and evolve the conversation around the existing ones.

Types of SIGs

Currently, there are two types of SiGS that have emerged to move forward some aspect of using OAS, with 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.

• Overlays (Repo) (Slack Channel) - SIG focused on defining the overlays specification for OAS.
• Security (Repo) (Slack Channel) - SIG focused on moving forward security portions of the specification.
• Workflows (Repo) (Slack Channel) - SIG focused on building workflows with multiple APIs using OAS.
• Service Level Agreement (Repo) - SIG focused on the SLA extension being developed.
• Codegen (Slack Channel) - A SIG focused on moving forward the code generation conversation.
• Formats (Repo) - SIG focused on the formats registry effort.
• Lifecycle (Repo) (Slack Channel) - SIG focused on defining the API lifecycle around an API being developed using OAS.

The other 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 withinn specific industry.

• Travel (Repo) (Slack Channel) - SIG focused on using OAS within the travel industry.
• Finance (Repo) (Slack Channel) - SIG focused on using OAS within the finance industry.

These are just the first wave of SIGs to be formalized in the last six months, with some of them existing in various forms before the door was opened in May of 2021 for groups to be formed using a less formal review process--encouraging the creation of SIGs with as little friction and allowing them to grow organically over time-based upon activity defined by each group.

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 - Email @ncaidin with LF for setup.
• 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.

That represents what is currently in use to manage SIGs. None of these are required but should provide a set of common practices to consider. If there are other things 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.

Relationship to Other Existing OAI Groups

SIGs are intended to operate independently of the Technical Steering Committee (TSC), marketing group, and ASC steering committee, moving forward at their own speed, providing regular sync with existing groups, and following the process that is already established.

• Technical Steering Committee (TSC) - Each SIG has the option to bring regular updates to the weekly TDC meeting, providing a short and concise recap of what has been happening within the SIG. Establishing changes to the spec as an extension or overlay, and then submitting for formal review using the existing TSC proposal process.
• Marketing Group - Each SIG has the option to bring regular updates to the weekly marketing meeting, providing a short and concise recap of what has been happening within the SIG. Stories, social media, and other related activities can be suggested to the marketing group for further consideration.
• API Specifications Conference - Each SIG has the option to bring regular updates to the ASC planning meetings when in operation, providing a short and concise recap of what has been happening within the SIG.

Designated SIG leadership are encouraged to bring short updates to existing group gatherings as required but should follow existing group rules and processes when it comes to making contributions or requesting attention or resources from a group.

OAI 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. Neal has created a pull request in the main specification repository for gathering SIG titles, descriptions, and other information. This issue, as well as the supporting the Kanban board is just working to try to continue formalizing and communicating the structure and process for SIGs but does not claim to be the formal process, or is comprehensive--it is just an attempt to capture what is happening in motion.

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.

[swaldron58]

Great work!
Suggestion and a request
for sig-travel I added a project board connected to each issue. https://github.com/OAI/sig-travel/projects/1
Trying to get more task orientated to keep things moving.
my request is to have a common calendar for the sigs. Nothing fancy, just somewhere to see at a glance when the various sigs normally meet. Less important, a common tool for video conferences. @kinlane, pick anyone you favor but along with a common calendar, list how to get on the call in a more repeatable and predictable way.

[kinlane]

Some notes from latest SIG planning meeting:

Nick - Workflows

• Statement of Work
• How We Run Things
• How Do We Start Meetings
• Github Barrier
• Code of Conduct Slide

Ron - Overlays & Formats

• A repeat of Questions Already Asked
• Document the Process
• Discussions are Better Than Issues
• Where Does OAI Stand in Relation to SIGS (Owner, Support)
• Can Anyone Create SIG?
• How do we market the SIGs?
• Code of Conduct Page on Github - Need official statement
• How should be things licensed?

Overall

• Dedicated Page on Site?
• Calendar (OpenID.net)?
• Google Docs (Shared OAI Area) - Create a Folder
• Cross SIG sharing and communication?
• Communication Broadcast to SIGs?