Openapi-specification: Officially supported 3.x spec parser(s)

[dtzar]

There are numerous tools and products being developed which need to fundamentally parse OAS files and do something with them, including validation. Many people are duplicating effort for this extremely important initial step and it would be great to have an officially supported or at least common collaboration OAS parser, where this is the code's only function. Injest a YAML or JSON OAS file and output an object version of it in code.

With a common or officially supported parser (perhaps one per code language), then the growth of the tooling ecosystem and validation tool(s) will be significantly quicker to accelerate and be able to more easily and quickly handle changes and updates to the specification.

This was started out of a conversation with @BigstickCarpet @noahdietz @mrhegemon @earth2marsh

This would also apply to these existing project/product owners, so tagging them here:

• KaiZen-OpenAPIParser @reprezen
• StopLight @marbemac
• Apicurio Studio @EricWittmann
• Openapi3-ts @metadevpro

[EricWittmann]

Sounds like a great idea to me. I've actually created just such a layer for Apicurio with the intention of having it theoretically become an official OAS parser. It's written in TypeScript and can be found here:

https://github.com/Apicurio/oai-ts-core

I never really raised it as a possibility before after some previous discussions (I forget where precisely) indicated that there was no desire within the OpenAPI community to host or sponsor any actual code projects.

[darrelmiller]

The goal of the OAI has to be focused purely on producing a specification, not tooling. Reference implementations tend to end up being de-facto standards and can end up introducing assumed behavior that is not in the specification.

The idea of having the OAI pick a "winning" implementation per language and then have to guarantee interop between those "winners" sounds like a logistical and political nightmare.

OSS communities are used to having alternative implementations of capabilities. Duplicated effort is nothing new because developers have different ways of doing things. OSS communities have a natural selection process for picking winners. I do not believe the TSC should have the authority to do that on behalf of the community.

It is the future plan of the OAI to introduce a process where an implementation can be identified as "spec compliant" by the OAI in order to give consumers confidence in the compatibility of the tooling.

[dtzar]

I assume that there will be a tool required to parse the spec in order to identify it as "spec compliant". I fully understand the general desire to not "officially" support a tool and especially not multiple versions of the tool for different programming languages. Perhaps to support the "spec compliant" process - one tool is used and officially supported with the intent of achieving that goal alone.

IF none of this is something OAI wants to support - My hope was to foster communication and collaboration amongst people creating this tooling and wasn't aware of a better place to initiate the conversation.

[darrelmiller]

I assume that there will be a tool required to parse the spec in order to identify it as "spec compliant".

Sorry, I don't follow.

Some tools may be able to be validated automatically with a set of test cases. Other tools, especially Visual editors will likely have to be validated semi-manually. Which is not going to be fun.

If there are issues relating to interoperability between tooling, due to ambiguity in the spec, then this is definitely the place to have the conversation. The Implementations.md file is a central location for implementers to discover each other. We could potentially setup a mailing list for tooling folks to have conversations around tooling. /cc @OAI/tdc

[mrhegemon]

Hi Everyone,

I just saw this long email chain in my spam folder. Would we be willing to restart this conversation?

Are people free for a conference call next week?

I’d love to talk OAI tool strategy and screen share our current SDK/Client work to talk about how we could all collaborate and standardize our work.

[EricWittmann]

I'd be up for that. Might need to wait for the week after though as it's US Thanksgiving next week - so a short week for us 'mrrricans.

[mrhegemon]

How about Tuesday 11/28 @ 2 PM PST?

Which emails should I send an invite to?

Join the call: https://www.uberconference.com/bitscoop
Optional dial in number: 585-632-4655
PIN: 91461

Thanks.

William Broza
Co-Founder & CEO
BitScoop Labs
[phone]
https://bitscoop.com

On Nov 14, 2017, at 9:17 AM, Eric Wittmann [e-mail] wrote:

I'd be up for that. Might need to wait for the week after though as it's US Thanksgiving next week - so a short week for us 'mrrricans.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub https://github.com/OAI/OpenAPI-Specification/issues/1398#issuecomment-344330843, or mute the thread https://github.com/notifications/unsubscribe-auth/AE3iILI8D1LmdZuoEDSEZAW7-9ihHMKMks5s2csQgaJpZM4QQQZ9.

[dtzar]

Awesome - I'm in! I'll add it to my calendar.

[MikeRalphson]

Ditto (for swagger2openapi / APIs.guru).

[webron]

Thanks everyone for the enthusiasm around this topic. As previously stated, the OAI deals only with the spec, and not implementations or tools. Personally, I don't think we should have only one implementation per language, and there are numerous examples around other projects out there. I see benefits to it.

We encourage vendors to work together, and anyone who wants to share their work is welcome to do so in our Implementations.

Regularly, I would close this ticket at this point because, as said, it is outside of the purview of the OAI and the OAS. However, we like to see cooperation in the community. We're working on providing a platform for users and vendors to have more generic discussions that are not directly related to changes to the spec itself, but until there is one, this issue will remain open to help out. Just keep in mind - this does not mean the OAI or OAS endorse any specific implementation.

[EricWittmann]

Sounds good to me. I've added it to my calendar as well. Email addy in my profile.

[dtzar]

@mrhegemon did you ever publish the code you have which does the parsing somewhere public?