oai / projects Goto Github PK

This is a list of current discussion items for the OAI Chair and LF PM meeting:

• Additional Leadership
• SIGs
• Office Hours
• Membership
• JSON Schema Documentation

This page defines the approach to the development of a tooling repository and engagement strategy for the OpenAPI Initiative, specifically in how to add tools to the directory. It reflects:

• The statement of work defined in the OpenAPI Projects repository.
• The initial requirement to get the repository up-and-running.

This proposal will evolve over time as the initial cut of the repository is established and tools ingested.

Problem Statement

It’s a fact that any programming language - API specification-related or otherwise - is only as good as the tools that support it. Without relevant and workable tooling a community built around a given programming language will wither and die, as the users of the language - developers - do not have the affordances required to be productive human beings.

OpenAPI does not have a tooling problem in the sense there is no tooling - there is lots of it. However, easily finding the right and relevant tools can be a challenge and it is perceived that the OpenAPI Initiative could do more to help tooling makers publicize their wares. It’s not that the repositories don’t exist - there’s https://openapi.tools and https://apis.guru/awesome-openapi3/ - but these may be considered opinionated in their construct or coarse-grained in their data selection. There is also limited means to drive quality in the data, as they either work on snapshots based on automated searches or best efforts of maintainers with limited time available. The current mechanism of storing tools in the IMPLEMENTATIONS.md in the specification repository is also not fit-for-purpose, based on the number of pull requests that require merging.

The goal of the Tooling workstream is therefore to address by developing a dedicated repository for tooling that can become a ubiquitous community resource with the means to provide curated content.

To that end there are a number of specific objectives in its creation:

• Federate and merge existing repositories.
• Curate content.
• Publish centrally.

These objectives are expanded on below.

Federate and merge existing repositories

The first objective is to bring together the data that already exists in the community. It makes no sense to start from scratch given the considerable collateral that we already have from existing resources. The design approach is one of “loose-coupling”, where we can draw from existing repositories on an ongoing basis without affecting their presence or modus operandi.

The existing resources in scope are as follows (and already mentioned above):

• https://openapi.tools
• https://apis.guru/awesome-openapi3/
• IMPLEMENTATIONS.md

These will be combined into a single, attributed list in the Tooling repository and, in the case of https://openapi.tools continue to be merged into the near future. There are two significant advantages to this approach:

• Community: Repositories that are managed by active members of the OpenAPI community have buy-in from their contributors. We should facilitate continued use of the source repositories as “cutting them off” may alienate them from supporting the new Tooling repository.
• Wealth of knowledge: The repositories listed above hold significant collateral that can be drawn upon and curated to significantly seed the new Tooling repository. It will give us a significant head start.

The table below shows the in scope repositories for the first iteration:

Repository	Approach	Rationale
https://openapi.tools	Merge	The repository has many active contributors and a good base set of metadata. We should continue to leverage the buy-in to this repository. The approach of federating has been discussed with Phil and as long there is attribution he is down with it (and it is supported by the underlying license).
https://apis.guru/awesome-openapi3/	Migrate	Mike Ralphson has already discussed using this as the basis of an OpenAPI Initiative Tooling repository, as discussed in this paper. We should migrate the existing data/data captured mechanism (a GraphQL query on a given GitHub tag, Bayesian analysis of the readme of each repository) across to the Tooling repository and work with Mike to work out a future for the existing repository
IMPLEMENTATIONS.md	Migrate	The content of IMPLEMENTATIONS.md should be migrated across to the Tooling repository. This includes any outstanding pull requests - owners of those requests should be notified of the transition.

The “Merge” approach for ingesting https://openapi.tools will be extensible, in that it will be future-proofed to allow us to bring other repositories and sources of information as we uncover them. This will allow us to always build on the existing community efforts, hopefully extending buy-in to our unified repository.

Analyze and curate content

The combined dataset will be housed in the new Tooling repository and be updated on a daily basis with changes from federated repositories using (most likely) GitHub actions as the build tool. Individual contributors will also be able to contribute to the repository where required (for example, where the tool is commercial and closed source).

The Bayesian analysis and GitHub metrics (Stars, etc.) will then be expanded to incorporate more metadata and extended across all repositories in an effort to ensure consistent categorization. This will help drive qualitative analysing of the data to ensure that anything that turns out irrelevant can be filtered (for example: tagged repositories with boilerplate code or limited community value, dead repositories, etc.)

Mopping up any failures in the automated analysis will be undertaken manually.

Publish centrally

The final objective - publishing the information for the use of the community - should be straightforward in terms of look-and-feel, i.e.:

• Inherit current OpenAPI theme.
• List of tooling in the style of https://openapi.tools.

However, this will be accompanied by filtering mechanisms that will make the most of metadata we can gather, viz.:

• Category.
• Open source vs commercial.
• GitHub metric (stars, etc.)
• Last update.
• License type.

The power of the new Tooling repository lies here: exploiting the available metadata to ensure our efforts enable the OpenAPI community to make informed decisions in their choice of tooling.

This is meant to provide an overview and statement of work for profiling and engaging with API providers across multiple industries:

---

The OpenAPI Initiative (OAI) needs ongoing assistance in the discovery, profiling, and engagement with API providers. There are many different types of API provides who are already using OAS as part of their operations, and we'd like to know who they are, profile what they are doing, and explore ways in which we might be able to engage with them more and get them involved in the community. Working to identify the things being done with OAS by interesting API providers, then work to make that better known to the OAS community, and wider API sector.

Statement of Work:

• Discover new and interesting API providers using OAS.
• Document details like name, description, URL, and Twitter.
• Try and engage with new members to see if they know the OAI.
• Write blog posts about how API providers use OAS in their operations.
• Suggest social media about providers we can publish via multiple channels.
• Help drive engagement by the provider with the OAS community.

This work can be view via the project Kanban board for the profiling and engaging with open source tooling, and any questions, comments, or additional items can be published here.

This is meant to provide an overview and statement of work for curating and publishing API articles, podcasts, and videos within the OAS community.

---

The OpenAPI Initiative (OAI) needs ongoing assistance in the discovery, curation, and publishing of articles, podcasts, and videos from across the API community. There is a lot of work occurring already out of companies, organizations, institutions, and government agencies when it come to putting the specification to work, and this statement of work intends to help push forward formal but also volunteer community effort to help better showcase the great storytelling that is already happening.

Statement of Work:

• Discover interesting articles, podcasts, and videos showcasing work occurring around OAS 3.0
• Curate interesting articles, podcasts, and videos showcasing work occurring around OAS 3.0
• Publish interesting articles, podcasts, and videos as separate YAML lists within "Stories" Github repository.
• Document process for discovery, curating, and publishing of articles, podcasts, and videos to list.
• Publish articles, podcasts, and videos as simple HTML listing via the stories Github repository.
• Document process to encourage anyone to participate at any part of the curation process.

This work can be view via the project Kanban board for the profiling and engaging with open source tooling, and any questions, comments, or additional items can be published here.

This is meant to provide an overview and statement of work for profiling and engaging with open source tooling within the OAS community.

---

The OpenAPI Initiative (OAI) needs ongoing assistance in the identification, profiling, and engagement with open source tooling makers who have adopted OAS 3.0, or need assistance in migrating from Swagger 2.0 to OAS 3.0. This work involves helping establish a standardized process for identifying, profiling, engaging, and curating open source tooling within the OpenAPI community via Github, and then setting in motion the process to do this work with the goal of establishing, then maintaining an official OAI tooling catalog.

Statement of Work:

• Establish a list of open source tooling in YAML format.
• Setup a Github repository for managing OAS tooling.
• Manage list as YAML via a Github repository within OAI org.
• Establishing process for discovering new tools using OAS 3.0.
• Establish process for adding new tools to the YAML directory.
• Contact tooling makers so we can better understand their needs.
• Record tooling makers needs as Github Issues.
• Establish process for reaching out to tooling makers on regular basis.
• Label Github issues for organization and addressing.
• Establish a process for maintaining and updating tooling.
• Establish an HTML front-end for tooling catalog.
• Encourage tooling makers to be more involved in OAS community.

This work can be view via the project Kanban board for the profiling and engaging with open source tooling, and any questions, comments, or additional items can be published here.

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.

This is meant to provide an overview and statement of work for new member identification and engagement within the OAS community.

---

The OpenAPI Initiative (OAI) needs ongoing assistance identifying potential new members for the organization. Helping discover and profile API providers, service, and tooling providers who would be interested in joining in to help work on the specification, join in marketing discussions, as well as become a member of the OAI. The OAI would like to grow our membership so that it can reach a larger audience, and better serve our growing community of practitioners.

Statement of Work:

• Discover new API providers, service, and tooling providers.
• Document details like name, description, URL, and Twitter.
• Try and engage with new members to see if they know the OAI.
• Document potential members and outreach made to organizations.
• Work to first encourage more participation within the community.
• Work to secondarily understand if they are aware of member benefits.

This work can be view via the project Kanban board for the profiling and engaging with open source tooling, and any questions, comments, or additional items can be published here.

This is the proposed agenda for the OAI SLA SIG Meeting for June 18th, 2021. All of these tasks can be managed via the project Kanban for the SLA SIG:

• OAS SLA for Two API Providers
• AsyncAPI SLA for Two API Providers
• Blog posts about OAS and AsyncAPI SLA
• Social media posts about OAS and AsyncAPI SLA

Please add anything else you'd like to discuss to this issue, and feel free to submit an issue if you'd like to be added to the project calendar and Kanban board.

This is summary of project updates for the OAI marketing meeting on June 18th, 2021:

• Open Office Hours - We held the first public office hours, but primarily used for time on how to get word out about SIG activity.
• SLA SIG - Work to apply SLA spec to the OpenAPIs for two API providers, and one AsyncAPI for an asynchronous event-driven API -- then do some blogging and social media around it.
• SIG Planning - Started a new project to track on the details occurring across all SIGs.
• Content Curation - Renamed video curation to just content curation to help target blog posts, tutorials, as well as video content about OAI.

If there are any other project updates I've missed, please submit them below and join the marketing meeting to discuss.

This is meant to provide an overview and statement of work for showcasing and engaging with existing members within the OAS community.

---

The OpenAPI Initiative (OAI) needs ongoing assistance in engaging with existing OAS members, helping showcase what our members are up to when it comes to OAS, what the OAS can do to better support our members, and try to get members more involved in the OAS community. Many different types of organizations are attracted to be OAI members, so we need a creative individual to help understand the best ways we can showcase and engage with our membership base. Helping better drive growth within the OAS community while also strengthening our existing member relationships.

Statement of Work:

• Reach out to members to learn how we can better help them.
• Read the blog of our members to see if they are doing anything worth showcasing.
• Read the twitter of our members to see if they are doing anything worth showcasing.
• Suggest social posts that the OAS accounts can help amplify via multiple channels.
• Conduct weekly office hours to invite and engage with members about the OAI.
• Write blog posts about our member's usage of OAS within their operations or customers.
• Help drive member engagement with the BGB and existing OAI activities.

This work can be view via the project Kanban board for the profiling and engaging with open source tooling, and any questions, comments, or additional items can be published here.