Open Community (TDC) Meeting, Thursday 19 October 2023

[github-actions]

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
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

[duncanbeevers]

Formal linkage between Spec (markdown) and Schema (JSON).

1. Very-high level; what Artifacts is the OAI expected to provide?
2. How do these artifacts relate to one-another?
3. Can the disparate artifacts be generated from a common source? Can and Should they be better linked?

In this PR I bodge-together the OAS spec document markdown, and the schema JSON. The net effect is to make more of the rich text content from the spec document available as tooltips when editing schema documents.

I propose three pieces.

• Augmenting the Markdown spec with some kind of references, allowing for simpler + more consistent extraction of description + parameter data
• Creating tooling to process the markdown, and extract + validate this formal data
• Generating / Augmenting the JSON schema with this extracted + validated data

This helps bridge the gap between the spec (markdown) as document-read-by-humans, and the JSON schema which enforces the spec, and which is often the way in which developers actually interact with and implement APIs conforming to the spec.

[handrews]

Last week there was a request for a glossary on the Learn site. This PR starts one, and also offers a guide to referencing that we might want to discuss (the glossary and the referencing guide can be split into to PRs, but as there is a cross-link I posted them together to start with): OAI/learn.openapis.org#69

Discussion of processing models:

• 1000-word summary (please at least try to skim this - it is intentionally short and high-level!)
• details and examples

[MikeRalphson]

#3408 fix internal links in published versions of the OAS

[karenetheridge]

open PRs for review:

• the chart in section 4.8.12.4 shows that primitive and object types are also valid for style=simple #3380
• punctuation fix #3397
• switch the order of these styles in the tables (3.1.1) #3398
• switch the order of these styles in the tables (3.2.0) #3399
• the chart in section 4.8.12.4 shows that primitive and object types are also valid for style=simple #3401

[karenetheridge]

Generating / Augmenting the JSON schema with this extracted + validated data

A while back I added $comments throughout the v3.1 specification that provided links back to the specific part of the spec that defined those entities. e.g.

  "$defs": {
    ...
    "contact": {
      "$comment": "https://spec.openapis.org/oas/v3.1.0#contact-object",
      "type": "object",
      "properties": {
...