Open Community (TDC) Meeting, Thursday 20 July 2023

[github-actions[bot]]

NOTE: This meeting is on Thursday at 9am - 10am PT

Zoom Meeting link: https://zoom.us/j/975841675. Dial-in passcode: 763054 - Code-of-Conduct

In order to give some more visibility into the topics we cover in the TDC meetings here is the planned agenda for the next meeting. Hopefully this will allow people to plan to attend meetings for topics that they have an interest in. And for folks who cannot attend they can comment on this issue prior to the meeting. Feel free to suggest other potential agenda topics.

Please submit comments below for topics or proposals that you wish to present in the TDC meeting

The agenda backlog is currently maintained in issue #2482

Topic	Owner	Decision/NextStep
Reports from Special Interest Groups	TDC
Spec/documentation	Duncan
Moonwalk deployments, namespacing and external references	Darrel to try and steer conversation
AOB (see below)	TDC
Approved spec PRs	TDC
New issues / PRs labelled review	@OAI/triage
New issues without response yet	@OAI/triage

/cc @OAI/tsc Please suggest items for inclusion

[handrews]

Since @darrelmiller has proposed discussing referencing in the context of connecting deployments and shapes, here's my thoughts on that discussion so far in the context of Moonwalk.

---

I think the most interesting direction from discussions so far is separating "how do I import an external resource?" vs "how do I refer to an entity within the set of loaded documents?"

JSON Schema does both of these things with URIs (which will be IRIs in the future, and should be IRIs in Moonwalk).

OAS currently does most internal entity referencing with URIs, except for various places where it doesn't (operationId, the discriminator's map-by-name options, security schemes, and probably some other bits that escape me at the moment.

Importing external resources should be done with IRIs, because that's what they're for. Moonwalk just needs the ability for a document to set its IRI (and therefore internal base IRI) from within the document to make mapping identifiers and locations easier and more aligned with other media types.

Internal entity references could be done through a more uniform mechanism that ensures referential integrity and is easier for folks to understand than base URIs (I personally am baffled by how much folks struggle with base URIs, but I've read RFC 3986 countless times so I'm too much of a standards snob to be a useful data point for UX :stuck_out_tongue: )

The difference between these internal identifiers and, say, JSON Schema's "$anchor", is that "$anchor" works with URI / IRI fragments, which are scoped within a base IRI. _I think it would be better to import all internal identifiers into the same namespace, or introduce explicit namespace management as is done in programming languages to import module contents, rather than using base IRIs for namespacing.

Alternatively, commit fully to IRIs and don't use any non-IRI references (I notice that AsyncAPI has gone this route recently by changing how security schemes work).

[duncanbeevers]

I'd like to briefly discuss the role of inline documentation in the OpenAPI spec.

There is stand-alone, semi-structured documentation that lives alongside the spec; eg OpenAPI 3.0.2 documentation

• How are these semi-structured documents generated?
• Does it make sense to inline some of the documentation into the spec itself? What are the pros and cons?
• If it's not in the spec document, is there some other, more-structured form from which the documentation could be extracted, analyzed, and manipulated?

PR which reads from Markdown and augments OpenAPI spec document with documentation fields

[darrelmiller]

@duncanbeevers Maybe I am misunderstanding what you are saying but the Markdown document you pointed to is the OpenAPI specification. The JSON Schema is non-normative. We can discuss further in the call.

[duncanbeevers]

Thanks for the clarification today about the roles of the respective documents.

My understanding now is that the Markdown is the Source of Truth for the OpenAPI Spec, and that the JSONSchema document is a hand-maintained artifact derived from the Spec.

In the meeting today we discussed the use-case supported by including documentation from the Spec in the JSONSchema document. With this understanding, the TDC has context (and some ideas) about how this might (or might not) fit into the Moonwalk proposal.