Clarify resolving implicit connections (3.1.1)

[handrews]

NOTE: See PR #3856 for an alternative approach that may be simpler.

---

Fixes:

• Meaning of the term API in the operationId context. #381
• Many concerns that no one thought to file

This clarifies how to handle resolving implicit (non-URI-based) connections in multi-document OpenAPI Descriptions.

While the behavior is implementation-defined overall, two approaches are RECOMMENDED for tool developers and OAD authors: one that is best suited for sharing components among OADs, and one that is compatible with pre-3.1 parsing approaches and is convenient for breaking a monolithic document up purely for author convenience.

Note that the term "complete OpenAPI document" has been defined in another change (PR #3820) pending approval on the 3.0.4 branch. Also, some relevant Discriminator Object guidance around mapping with relative URI references is being added in #3822, also pending for 3.0.4.

Tthis will get backported to 3.0.4, but without the full-document part; the backport will be easy once we've agreed on the 3.1 approach.

Reviewer Questions

• operationId could resolve either from all Operation Objects in all documents in the OAD, or only from those reachable via the entry document's paths or webhooks fields
  • I settled on using every Operation Objects because it fits with whole-document parsing
  • For the case where only the entry document has an OpenAPI Object (and therefore Components Object), which is where the "via paths or webhooks" approach might make sense, the only thing this changes is if a Path Item Object in Components has an Operation Object with an operationId targetd by a Link Object, but that Path Item Obejct is not part of paths; it seems unlikely that the intent would be to exclude that Path Item Object and its Operation Objects as they are in the entry document
• I originally had wording suggesting implementors add opt-in support for a proposed future solution to a major limitation around Security Requirement Objects
  • I decided it was too complicated to do that and just replaced it with an acknowledgement of the limitation and a note that we expect to address it
  • I can take out the note if that seems odd, but I do think it is important to plug this gap ASAP, and let users know that we are aware of it even if we do not say that we plan to address it
  • If you want to see the "from future"-esque idea, you can see it here

[ralfhandl]

Need more explanation

[handrews]

@ralfhandl I've updated the text in several places (it's a separate commit so you can look at the individual diff) - please let me know if that makes things more clear. I appreciate your attention to detail here, because if the text confuses anyone on the TSC it will definitely confuse other readers who have much less context!

[ralfhandl]

Good clarification!

[handrews]

@ralfhandl I made some other minor updates, again as a separate commit.

[handrews]

I've converted this back to a draft because I realized I forgot tags, added them in the most recent commit, and then rethought the whole thing to have a single approach rather than two different ways to organize things. Here is the alternative PR:

• Alternative: Clarify resolving implicit connections (3.1.1- alternative to #3823) #3856

[ralfhandl]

I prefer the alternative proposal in #3856.

[miqui]

@handrews , @ralfhandl The language in #3856 is less confusing AFAIK (As a spec author (and trying to take a pragmatic approach)).

[handrews]

Closing as we accepted #3856 instead 🎉