Open TSC Meeting - January 16th 2020

[MikeRalphson]

NOTE: This meeting is on Thursday at 9am - 10am PT
Zoom Meeting link: https://zoom.us/j/975841675

In order to give some more visibility into the topics we cover in the TSC 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 TSC meeting

Topic	Owner	Decision/NextStep
Add support for webhooks as a top-level element #2103	@lornajane
Discussion on ReferenceObject outside schemas	@MikeRalphson
Extend current PR for making paths optional to create a collection of Path Item Objects in components.	[Ron/Mike]

/cc @OAI/tdc Please suggest items for inclusion

[darrelmiller]

How consistent should $ref's be?
Should we allow siblings to $refs in OAS.
Use of $id in $ref.

If $ref don't allow sibilings in OAS $refs, how do we make this clear to users?

[handrews]

If $ref don't allow sibilings in OAS $refs, how do we make this clear to users?

The use of sibling keywords with $ref in schemas relies on allOf semantics. One way to be a bit more clear is to explicitly tie $ref siblings to allOf, and if a component type does not support allOf then a Reference Object in that location cannot support sibling keywords.

I'm not sure how clear that will be for folks, but it would at least get people thinking about "what would an allOf mean here?" which is the correct question to ask.

For annotations like description, which might be a more relevant model for a lot of things, allOf doesn't have much inherent semantics- JSON Schema just says "if you are collecting annotations at all, you need to collect certain information for each occurrence of the annotation. When there's no instance (e.g. for generative use cases), a subset of that information is relevant (obviously there is no instance location to record, for example).

Applications have to decide what to do with that information. In general, the OAS should determine whether the "application" that makes that decision is the OpenAPI spec or the individual tools.

In this example, "outer" and "inner" are talking about dynamic parent vs child relationships. This includes both lexical parent/child, and runtime notions via references. e.g. outside of an allOf vs inside of one of its subschemas (lexical and also dynamic), or adjacent to $ref rather than inside the target of $ref (dynamic but not lexical).

For example, OAS could say "the outermost title overrides any inner title", or "all description values should be concatenated as separate paragraphs, starting with the outermost and ending with the innermost." Or OAS could say that individual tools can make their own conventions for that, or leave it as a configuration option for users. I believe some tools already make assumptions like this.

This would probably be the sort of question that would need to be answered for non-schema $refs, as they are working with things that are more like annotations than assertions.