Overlays Meeting (2022-03-15)

[kevinswiber]

Date: 2022-03-15

Attendees

• Kevin Duffey
• Kevin Swiber
• Josh Ponelat
• Ron Ratovsky
• Nick Denny
• Karl Scheirer
• Carol Kigoonya
• Maggie

Action items

• Work to place defined use cases into categories on Discussion #9. (All members will participate, and Ron has agreed to coordinate.)
• Reach out to JSON Schema team to ask about envelopes/placeholders (Kevin)

Open Questions

• Is it worth considering making Overlays OpenAPI-specific instead of JSON-generic when we start hitting edge cases?
• Could envelopes/placeholders be a problem solved by JSON Schema at some point in the future?
• Should we put more thought into how request/response interaction might influence the traits/groups use case category?

Review open Pull Requests

#18 Changed query language from JMESPath to JSONPath

#18

• Neither JMESPath nor JSONPath have a completed standard.
• JSONPath is working toward a standard in the IETF: https://datatracker.ietf.org/doc/draft-ietf-jsonpath-base/.
• Is there any active development around JMESPath?
  • There might not need to be.
• It might not be so important that the query language specification is approved by a standards body. What's more important is that it has versioned releases.
• Other query languages proposed from various channels:
  • JSONata: https://jsonata.org/
  • Jsonnet: https://jsonnet.org
• Whichever language is chosen, library support needs to be considered.
  • Libaries for query languages often return data. We also need them to return paths for found results.
• Will review asynchronously, as Darrel Miller (PR Author) isn't present on the call.

#17 Example showing setting default response

#17

• A new fixed field is being proposed, default, to insert values at a specified path when that specified does not exist in the source document.
• Will review asynchronously, as Darrel Miller (PR Author) isn't present on the call.

Review a list of use cases

Known use cases for Overlays.

Categories

• I18n / Multilingual support for OpenAPI
• Traits/Groups of re-usable components (eg: parameters/responses).
• Envelopes/placeholders (ie: pagination)
• Context specific API definitions (ie: one API definition, different views for different audiences)

Notes

• Pick a use case to narrow down scope of initial spec development.
• Could envelopes/placeholders be a problem solved by JSON Schema at some point in the future?
• Traits/groups aren't just about schema definition in OpenAPI.

[webron]

Meeting Recording:
https://zoom.us/rec/share/AdW3DuWHe3SMaGtHkYHQpo9HakkhdE8JF805_3Lxy8Egpox2yOZipO_tGm1o-9Ih.Lj9oH3jqv4YFBbS6

[kevinswiber]

RE: JSON Schema support for envelope use case...

Excellent response from @jdesrosiers on JSON Schema support for handling something like generics, Page<Product>.

My initial comment in the JSON Schema Slack:

The way we’re thinking about requires some kind of wrapping. If you look at line 32 of page.schema.json, we won’t know what will be referenced as an item on the page. It reminds me of generics in type systems, Page. Let me know if I need to provide more clarity. I appreciate you taking the time. https://gist.github.com/kevinswiber/4ee078f7bee175852587aca738377168#file-page-schema-json-L32

Jason's response, using dynamic references and dynamic anchors:
https://gist.github.com/kevinswiber/4ee078f7bee175852587aca738377168?permalink_comment_id=4100485#gistcomment-4100485

Would this help? With some use cases, I think yes. Worth further discussion!

[lornajane]

Closing this discussion from a past meeting, but it will still be available for reference.