"Guidelines for Naming Projects, Tools, or Organizations" section in the readme

[jmini]

With commit 7687728 a new section "Guidelines for Naming Projects, Tools, or Organizations" was introduced in the README. This issue is about understanding the consequences.

---

Found on GitHub:

GitHub Organization:

Several GitHub Organizations are already using OpenAPI as prefix:
https://github.com/OpenAPI
https://github.com/OpenApiFactory
https://github.com/OpenAPITools
https://github.com/OpenAPI-Tools-Automation
https://github.com/openapi-test
https://github.com/openapi-ro

Project name:

Several GitHub projects are already OpenAPI or openapi in their project name:
https://github.com/contentjet/openapi-ui
https://github.com/getkin/kin-openapi
https://github.com/oasis-tcs/odata-openapi
https://github.com/Mermade/openapi-codegen
https://github.com/Mermade/openapi-filter
https://github.com/Mermade/swagger2openapi
https://github.com/Microsoft/OpenAPI.NET
https://github.com/openapitools/openapi-generator
https://github.com/p1c2u/openapi-spec-validator
https://github.com/quen2404/openapi-diff
https://github.com/RepreZen/KaiZen-OpenAPI-Editor
https://github.com/RepreZen/KaiZen-OpenApi-Parser
https://github.com/xuzhg/OData.OpenAPI

Is the usage of open-api in the project URL better?
https://github.com/eclipse/microprofile-open-api (Project title in the readme: "Eclipse MicroProfile OpenAPI")
https://github.com/janephp/open-api (Project title in the readme: "Jane OpenAPI"

And some projects are using openapi3:
https://github.com/metadevpro/openapi3-ts
https://github.com/adwhit/openapi3-rust

---

While I understand the concern about the usage of the OpenAPI brand in third-party projects, I think that the rule as formulated in the readme is really hard to implement. There are a lot of projects out there (small one, big corporation one, foundation-backed one). I think that the having a lot of projects having adopted "OpenAPI" in their project names demonstrate the strength of the ecosystem.

Thank you in advance for your advises on how to read the section.

[darrelmiller]

@jmini Thanks for your feedback on this issue. I'm not sure I agree that the guidance provided is hard to implement. It is true there may be edge cases, but in general, ask the question, is the name of my tooling likely to be misconstrued by someone as an official reference implementation by the OpenAPI Initiative.

If a project is under a personal or company repo, then I don't think anyone is going to be confused about the authority of the project. If the organization is completely empty like https://github.com/OpenAPI
and https://github.com/OpenApiFactory then there is not much to be confused about.

However, from the list of repos above, the only one that does not clarify that the project belongs to a secondary identity, is openapitools/openapi-generator. I do appreciate the fact that on the organization page there is a note that clarifies that OpenApiTools is not affiliated with the OpenAPI Initiative. However, most folks are going to link directly into the repo and never see that caveat.

There is fairly strong user demand for reference implementations, but the OAI neither has the charter nor the resources to create those, and to do so would be unfair to community efforts. What I personally do not want, is people assuming that the OAI does have reference implementations because of unclear naming.

[jmini]

@darrelmiller, thank you for this message. Here some more questions we have with the @OpenAPITools/people.

@jmini Thanks for your feedback on this issue. I'm not sure I agree that the guidance provided is hard to implement. It is true there may be edge cases, but in general, ask the question, is the name of my tooling likely to be misconstrued by someone as an official reference implementation by the OpenAPI Initiative.

We can always ask that simple question but who's going to decide the "correct" answer. Let's start with the question "Do you think X is affiliated with OpenAPI Initiative?" where X is OpenAPITools.org in this case and depending on who you ask the question, you may get different answers: Yes, No, maybe, or other possible answers.

We think the important point is who's going to make the call to decide whether a particular name will cause potential confusion with OpenAPI Initiative. Is that done by a single person at OpenAPI Initiative? or the OpenAPI Initiative TSC going to vote?

Let's look at https://openapi.tools as an example. Arguably one may consider http://openapi.tools to be affiliated with the OpenAPI Initiative. From OpenAPI Initiative, should https://openapi.tools be renamed to something else to avoid potential confusion?

Disclosure: the OpenAPI Generator core team does not own https://openapi.tools. but we did submit pull requests (merged) to include "OpenAPI Generator" in the list.

If a project is under a personal or company repo, then I don't think anyone is going to be confused about the authority of the project. If the organization is completely empty like https://github.com/OpenAPI
and https://github.com/OpenApiFactory then there is not much to be confused about.

Thanks for elaborating a bit more on this. If "OpenApiFactory" publicly forks AutoRest (a code generator owned by Microsoft) to create https://github.com/OpenAPIFactory/AutoRest, will "OpenAPIFactory" need to be renamed to something else to avoid confusion?

What about https://github.com/regga-ws, which has several repositories and uses OpenAPI Initiative's logo but states clearly it's unofficial?

What if "OpenAPIFactory" leaves a very negative comment in a Github issue about open-source projects in general? Following what you said earlier

However, most folks are going to link directly into the repo and never see that caveat.

Your logic above implies "most" users reading the negative comment will not click on the Github account to uncover the fact that the account does not host any repository and therefore has nothing to do with "OpenAPI Initiative".

In this case, do you agree people cannot clearly tell the negative comment or the "OpenAPIFactory" account itself has nothing to do with "OpenAPI Initiative"?

(this is not to say we agree with the statement "However, most folks are going to link directly into the repo and never see that caveat")

There is fairly strong user demand for reference implementations, but the OAI neither has the charter nor the resources to create those, and to do so would be unfair to community efforts. What I personally do not want, is people assuming that the OAI does have reference implementations because of unclear naming.

We do not want people to be confused either as mentioned in our first email reply to Marsh. Do you mind sharing with us how many people you've spoken with to arrive at the conclusion "most" people are confused about OpenAPITools.org being affiliated with OAI? Would you consider a more objective approach by doing a vote on the Twitter account "OpenApiSpec" with the following question?

Do you think OpenAPITools.org (the parent organization of OpenAPI Generator) is affiliated with OpenAPI Initiatives?
Choice 1: Yes
Choice 2: No
Choice 3: Maybe

Poll length: 10 days

Here are two follow-up questions we've after reading your reply:

1. Does it mean "OpenAPI-Generator" (Github repo name) and "OpenAPI Generator" (product name) need not be renamed, which means these names conform to the updated guidelines?

2. In your opinion, do you think the OpenAPI Generator logo ([Discussion] Logo for this project OpenAPITools/openapi-generator#23 (comment)) also violates the updated guideline and will certainly cause confusion to the community?

[grokify]

Thanks for the discussion. Branding is an interesting exercise, especially when it relates to open source.

Organization Name and Project Names

If a project is under a personal or company repo, then I don't think anyone is going to be confused about the authority of the project. If the organization is completely empty like https://github.com/OpenAPI
and https://github.com/OpenApiFactory then there is not much to be confused about.

However, from the list of repos above, the only one that does not clarify that the project belongs to a secondary identity, is openapitools/openapi-generator. I do appreciate the fact that on the organization page there is a note that clarifies that OpenApiTools is not affiliated with the OpenAPI Initiative. However, most folks are going to link directly into the repo and never see that caveat.

It seems like most of the concern is about the use of the organization name and the project name together. Here are some additional questions:

Some questions:

1. What are OAI's thoughts on the go-openapi organization at https://github.com/go-openapi? The organization description is currently "OpenAPI Initiative golang toolkit" and they have several projects, unlike the ones mentioned. Should they change their organization name and / or description?
2. It seems the OpenAPI Generator project name by itself is not an issue, but there is concern when associated with the organization name. Also, the organization name seems to be acceptable by itself since it has a disclaimer at the top of the page. On the project page, there is an existing disclaimer that says the following in the README.md. Would putting such a disclaimer in the GitHub repo description at the top of the project repo page alleviate these concerns?

‼️ Both "OpenAPI Tools" (https://OpenAPITools.org - the parent organization of OpenAPI Generator) and "OpenAPI Generator" are not affiliated with OpenAPI Initiative (OAI) ‼️

Organization and Project Logos

In open source, there is a tradition of modifying logos for related projects. This gives a sense of community and association. For example, several organizations / projects that have their logos modified on a regular basis include Linux (penguin), Android, Go (gopher) and Python. Given the many GitHub repos that mention "openapi" in the name there is community interest around OpenAPI. Would OAI be supportive of projects making derivative logos like the other efforts mentioned?

[jimschubert]

Regarding the logo, I'd like to add that I based the logo off of a Robot wall art design in my child's room that we bought from Target. I added a barbell because this is commonly understood as an "interface" from UML.

It took me 15 minutes to create the logo.

The only similarities with OAI logo are the colors.

[darrelmiller]

So, @jimschubert you are suggesting that other than the colours, the layout of these two logos is co-incidental and there was no intent to create something that was similar?

[darrelmiller]

@jmini We would like the person creating the project to make the decision as to whether there may be confusion. I believe I can safely speak for the TSC in saying that we have absolutely zero interest in being intellectual property police. We have absolutely no interest in doing anything that would discourage community involvement.

What I am asking is for the project owners to review the naming decisions they have made and ask themselves the question, could this cause confusion in the community. Could someone mistake this project for a reference implementation? Could someone mistakenly interpret the naming as being an indication that the Swagger-codegen project is no longer a maintained effort and that this project is a replacement. The specification has been renamed from Swagger to OpenAPI and the OAI members have spent a significant amount of marketing effort explaining this transition. What is to stop someone from assuming that Swagger-CodeGen has just been renamed to OpenApi-Generator? It's forked from the same code-base, right? It has many of the same contributors. Do you believe my concern for these confusions are unfounded?

If the openapi-generator project team feel these concerns of mine are unfounded, that's their choice. I've given my opinion. The document we are discussing are guidelines that are intended to encourage constructive community behavior, nothing more.

[grokify]

As someone who works in a team that heavily uses OpenAPI / Swagger Spec and who used Swagger Codegen, only recently learning about the OpenAPI Generator project some time after it was created, I can provide some thoughts for @darrelmiller's questions.

Could someone mistake this project for a reference implementation?

It did not occur to me OpenAPI Generator (or any code generator) could be a reference implementation, specifically due to the complexity of the OpenAPI Spec and the fact many organizations still hand-build official SDKs on GitHub.

Also, if there were such a reference implementation, I would expect it to come from https://github.com/OAI because anyone can create any organization name on GitHub. It is first come, first served, like Twitter handles.

Could someone mistakenly interpret the naming as being an indication that the Swagger-codegen project is no longer a maintained effort and that this project is a replacement

Normally one wouldn't look at project B to determine if project A is no longer maintained. When I learned about OpenAPI Generator, the way I checked the status of Swagger Codegen is to check the Swagger Codegen repo and see if:

1. the README.md has a deprecation notice - there isn't
2. there are recent commits - there are
3. there are recent PR reviews / merges - there are

If there's no deprecation notice and there is recent project activity, then the project looks alive, regardless of what some other project is doing.

What is to stop someone from assuming that Swagger-CodeGen has just been renamed to OpenApi-Generator?

In addition to the fact the Swagger Codegen repo still exists with recent activity and no deprecation notice, the OpenAPI Generator README.md history section covers this and mentions it is a fork, which is a commonly known event in open source software, distinct from a rename.

https://github.com/openapitools/openapi-generator#63---history-of-openapi-generator

Also, if the Swagger Codegen project was actually renamed, I feel OpenAPI Codegen would be the appropriate new name. This is because "Codegen" is the defining part of the current name and would provide a sense of continuity.

Do you believe my concern for these confusions are unfounded?

As someone who did not have any idea what OpenAPI Generator was, read the README.md and did some Internet searches, it was clear that it was a fork and not the same project, and also that the original project is still alive with activity. I can't speak for others, but I was not confused.

I appreciate all the effort that went into, and is still going into, both projects. I am following Swagger Codegen progress and interested in the re-architecture on the 3.0.0 branch.

[jimschubert]

@darrelmiller just looking for clarification on the logo...

• Are you saying that no community project can use common design elements such as 45° orientation, padding between elements, or a UML-like barbell?
• What exactly are the modifications you're suggesting?
• Are you saying that this logo can be confused for the OAI logo?

I feel like you're suggesting that I copied the logo, which I didn't. I will be happy to share the Affinity Designer project file.

I admit that I used certain design elements to allow the community to associate our project as a tool specific to OpenAPI specifications. I fail to understand why OAI considers this a no-no.

[darrelmiller]

@jimschubert I would appreciate it if you didn't put words into my mouth. If you re-read what I wrote, I made zero comments about the logo other than asking you to clarify your statement. I certainly made no statement about what OAI considers a no-no.

I am only concerned about the potential for confusion. As someone who has spent the last two years incessantly explaining to people the difference between OpenAPI and Swagger, I am hyper-sensitive to this issue.

@grokify It is great that you have a process of due diligence when working with OSS projects. If only everyone was a diligent as you.

It appears to me that the members of the OpenApiTools org feel that their actions will have no negative impacts on the community and are enthusiastic about defending that position. I have more constructive things that I could be doing than debating this. I'm prepared to leave it at agreeing to disagree.

[jimschubert]

@darrelmiller if you weren't suggesting that a logo which looks similar with the design elements we've discussed in this thread is against the guidelines, then please explicitly state what you're asking me about.

I think the 3 clarification points I've asked for are reasonable questions, and I'll await responses.

[darrelmiller]

@jimschubert You already answered my question. I asked " there was no intent to create something that was similar?" and you replied "I used certain design elements to allow the community to associate our project as a tool specific to OpenAPI specifications. "

Regarding your questions, I believe I made my position clear.

[jimschubert]

@darrelmiller I appreciate that you edited your original response. My questions in this thread aren't meant to get under your skin, I'm just asking for clarifications which I don't feel like I've yet fully received.

To explain why I have questions, openapitools/openapi-generator was released on June 1 2018. On June 8 2018, this repository was updated via a597520 to include the following guidelines about the logo:

For example, if you're considering using the barbell element or the segmented circle, you may want to reach out to the OAI proactively to avoid a rebranding exercise later.

Being that I can't reach out "proactively" weeks after I created the logo, I'm asking my questions here and seeking further clarifications on these guidelines.

Also, I have a few additional questions based on a comment removed by your edit. I thought you were on the TSC, is this incorrect? If incorrect, what's your role? And is there an org chart or something which may clarify my confusion?

Thanks

[JFCote]

Disclaimer: I was a contributor to swagger-codegen for almost a year before becoming a Java Technical Committee member and then becoming a Core Member. Then, the fork happened and I became a core member of openapi-generator. This reply is MY own opinion and I'm NOT talking for the rest of the team or any member of its community.

First of all, let's look at this "problematic" in another angle. The OAI's goal as described here is to "create, evolve and promote" the OpenAPI Specification. You guys should be VERY happy each time a new project implementing your specification pops on the Internet. Your goal is that when someone search for "OpenAPI " on Google, he found a tons of tools and utilities to do whatever he want with its API. He want to see that the specification is alive. You don't want the user to found "RAML" or "API Blueprint". These are the real enemies.

You should not care about how people hear about "OpenAPI ". Did they find with OpenApiTools ? Did they find it with Swagger? Swagger Hub? Nobody cares. The end goal is the same for us all: Have people using OpenAPI with the tools of their choice.

I thinks it's pretty normal for a tools using a specification to have the name of the specification in its name. Imagine if the MP3 was forbidden in project name. How do you call a WavToMP3 converter? (That may not be a perfect example, but I'm pretty sure you understand what I meant)

Again, we, as much as you, want people to find tools when they are searching for tools to work with OpenAPI. If it's clearly said on all our important pages that we are not affiliated with OAI, then I don't see the problem at all. It's a win-win situation where we provide tooling for your specification and more and more people start using your specification all over the world.

As for the logo, I'm no artist but I can say that beside looking a bit similar, it is clearly not a "copy paste".

As for this:

What I am asking is for the project owners to review the naming decisions they have made and ask themselves the question, could this cause confusion in the community.

In most open source project, there are no "project owners". The project is run by the community and that was one of the main reason core members moved from swagger-codegen who was run by a company in the background (plus super bad decision related to breaking changes). We are 100% transparent and public and most decisions are made as a team. The name decision was made via multiple discussion by many many people.

I hope you and other OAI will answer the recurring question asked by our team members in this thread. They are simple and will help a lot to understand the problem. Again, I think there is not problem at all and that our project should work with you guys because we are on the same boat.

Have a good day!

[darrelmiller]

@jimschubert Yes I am a member of the TSC (members are shown here). If I am making statements that convey the policy/decisions of the TSC I will try to be very clear about that. This thread has been about expressing my feelings on the situation as a community member.

It is true that the guidelines were created as a reaction to the perceived issue with the naming of the OpenApiTools/OpenAPI-Generator, so the guidance about proactively reaching out obviously isn't helpful for you. The goal was to prevent us from getting into this situation again.

It is also true that we had no idea how to write these guidelines in an effective way. We are devs and PMs, most likely much like yourselves. We are not lawyers. We perceived a problem and we attempted to provide guidelines to prevent that from happening in the future.

We don't want to ask you to change the name of your project, or change your logo, we would rather be working on features that go into OpenAPI 3.1. But sadly as TSC members we also must deal with other issues. We (the TSC) are concerned about the naming. However, there are varying degrees of concern amongst members. There isn't concensus on what, if any, action should be taken.

Our hope was that by reaching out to you, we could explain our concerns and we could resolve the issue. Secondarily we decided to update our guidelines to reduce the chance that this would happen again. Sadly we have descended into analyzing the words of the guidelines.

I have tried to convey the intent of the guidelines rather than answering direct questions about what the guidelines do and do not allow. Much like debating a Code of Conduct, if we have to define precisely what is and isn't allowed, we are going to have a world of pain.

If you have suggestions on how to re-phrase the guidelines in a way that clearly expresses the intent, we are open to suggestions.