OpenAPI Definition

[jamesdwilson]

In the interest of rapid development, what are your thoughts on providing an OpenAPI/swagger definition file?

This can be used to generate API endpoint source code as well as check validity of endpoints.

[jamesdwilson]

@schnuerle Hi is there any update on this or do you know of ANY computer-parsable technical specification format we can make use of to help us rapidly develop our API? As far as I can tell it is only available in loose wiki/markdown style text documents.

Thank you

[schnuerle]

Hi @jamesdwilson. Right now we don't have a schema for CDS 1.0, or something similar like Swagger. It may come in the next release, if we can find a community member or members to lead the effort and do the work, maybe with the Working Group Steering Committee.

We could also look at funding this work if there is a demand, so I appreciate your efforts in pushing for this. I hope others will chime in too to help get it prioritized. As more orgs start using it after this first release, I imagine there will be a push for it.

For MDS, we do have a schema which you can see an example of here, and there has been a call for a swagger definition or OpenAPI defintion there too.

[schnuerle]

If time allows, we will bring this up for discussion at the MDS public Working Group meeting tomorrow, so please comment here or attend and bring your thoughts.

It will be MDS focused (not CDS) but the need for this in both MDS and CDS could help make it happen, the volunteer base would be larger to help with the work, and the solution will be the same for both specs to make them consistent within the OMF.

The Curb Work Group Steering Committee had multiple members that were both interested in this idea, and willing to spend some time and share their expertise on it, including the option of Stoplight.

[jamesdwilson]

Not my call I know but Stoplight looks like a good option to me, assuming there is always the option to export all data.

RE: MDS working group meeting, I like this a lot, but wondering what and when the impact will be on CDS as there is intentionally no overlap on CDS for 1.0 as far as I understand. Isn't MDS planned for a potential future version of CDS?

Thank you

[schnuerle]

Yes there is no current overlap in the spec between CDS and MDS yet, and that was intentionally for the first release. But I expect there to be connections (like referencing MDS trip IDs or CDS curb zone IDs, etc) between them in the next releases (MDS 2.0 and CDS 1.1 or 2.0).

We have open Issues to discuss there now.

• CDS: MDS Alignment #17
• MDS: CDS Alignment mobility-data-specification#731

For OpenAPI or equivalent, what I meant was the solution we pick should be the same and work for both specs, to reduce the overhead and remain consistent with the OMF organization.

[schnuerle]

This topic will be the entire focus of our next public working group meeting tomorrow. Please come if you can @jamesdwilson.

[schnuerle]

There is now a feature branch in this repo called feature-openapi where work will be started by the WGSC, which will lead to a pull request, and the WG can contribute with comments, their own pull requests, etc. cc @michael-danko-passport @BigIdeas.

The work will also be a topic for next week's meeting.

[BigIdeas]

@michael-danko-passport @schnuerle I just pushed a commit to the feature-openapi branch that adds an OpenAPI spec file for the Curbs API. It is basically a copy / paste from the API definition in the README. Feel free to see how that looks in Stoplight or any other editor / viewer tools, and make any updates you want to it.

[schnuerle]

@BigIdeas That looks amazing. I renamed it curbs.yaml in keeping with our MDS naming conventions (eg provider trips, if that's ok. Here is the direct link to the file:

https://github.com/openmobilityfoundation/curb-data-specification/blob/feature-openapi/curbs/curbs.yaml

Did you write all of it by hand or use a tool? Have you tried it in any editor/viewer tools?

Would be interesting to see someone like Automotus, Populus, Passport, Pittsburgh, or others who have implemented CDS use it to validate their own Curbs feeds and report results back. @jlarsonOmahaNE @zanebclark

[schnuerle]

I created Pull Request #100 for this, which can allow for line-item comments.

[BigIdeas]

Did you write all of it by hand or use a tool? Have you tried it in any editor/viewer tools?

I used Stoplight's editor to get it started and then filled the rest in by hand. I've only viewed it in Stoplight (mainly to check for syntax errors).

It's using version 3.1.0 of the OpenAPI spec (the current version), and it looks like Swagger's tools only support up to version 3.0.3 which is why I've only checked it in Stoplight. I think it would be pretty trivial to downgrade the spec to 3.0.3 if we want to for compatibility though.

[schnuerle]

Here it is for others to view in Stoplight's online viewer, in an OMF branded account:

https://openmobilityfnd.stoplight.io/docs/curb-data-specification/4wvvx7c8j5ymv-cds-curbs

[schnuerle]

Instead of putting the OpenAPI YAML in the CDS repo, I created a new repo where this schema code could live. Just a draft and the WGSC will be discussing this in more detail soon.

https://github.com/openmobilityfoundation/cds-openapi/blob/main/README.md

Updated Stoplight draft with placeholder for all APIs:

https://openmobilityfnd.stoplight.io/docs/cds-openapi

Added some examples to our working doc of what other orgs are doing in this space (feel free to add more examples):

https://docs.google.com/document/d/1PoB-p9LDUDwbaLtzigPLlZDwPk-PFdJPqkGvso9wPEs/edit#heading=h.71j9mocuqmvo

[schnuerle]

Here's where current work is being done by @michael-danko-passport:

https://github.com/openmobilityfoundation/cds-openapi/tree/v1.0.0-dev

[schnuerle]

FYI we have the complete MDS 2.0 OpenAPI definition and Stoplight page up and running now!

https://openmobilityfnd.stoplight.io/docs/mds-openapi/

[michael-danko-passport]

@schnuerle As a reminder, we still have the following issue opened up in the cds-openapi repo for updating the home page documentation. As I saw this update I went to check it out and still see the default boilerplate.
openmobilityfoundation/cds-openapi#4

[schnuerle]

@michael-danko-passport I did update the home page as part of our MDS 2.0 OpenAPI work. You can see it here with links to both the CDS and the MDS work on GitHub and Stoplight.

Now that we have that up and running, it would be great to 1) finish the work on OpenAPI for CDS and 2) structure it to match how it was done in MDS.

For MDS, we have each API defined as such, with each endpoint under it, and then schema definitions below that:

With CDS, we have it arranged a bit differently now, with all APIs under one level and schemas under that too:

What do you and @BigIdeas and @jamesdwilson think it would take to finish and align the schemas and endpoints like in MDS? It could be part of a 1.0.1 patch release as part of PR #100 I've worked on.

Note we are also now off the free version and are paying for Stoplight, so we have some of those capabilities.

[jamesdwilson]

Hi @schnuerle - respectfully and just FYI, I have moved on from this project. Take care!

[schnuerle]

We will be talking about this at next week's Working Group meeting for inclusion in a forthcoming CDS 1.0.1 patch release, so please attend if you can.

[schnuerle]

Merged with #100 PR