Make paths object optional

[MikeRalphson]

No description provided.

[darrelmiller]

What's the trigger for this? My recollection is that Ron has some historical reason for why it was a good idea to force paths to be there, but I don't recall why.

[MikeRalphson]

1. Overlays
2. Use of fully valid OAS documents as $ref targets.

[darrelmiller]

I don't have any objection to this and I think it opens some interesting doors for the future possibility to an alternative root level object (but shhhh, don't tell Ron that).

[MikeRalphson]

Indeed, let's keep this between ourselves.

[MikeRalphson]

"OpenAPI Document" within "Definitions" needs revising. Possibly also ACL descriptions. Look at object descriptions such as license which refer explicitly to an "API".

To be reworked into "what" we are trying to achieve, not "how".

[darrelmiller]

I think this is a valuable addition as we get closer to making overlays possible. It also is useful for using OAS documents as component libraries.

[webron]

I think in order for this to become complete, we should consider adding 'path items' under components as that's something that can be referenced but not defined integrally inside an OpenAPI definition (except through extensions). If we add it, then we can fully define OpenAPI component documents.

Another thing to consider is adding wording that would explain that if paths does not exist, it MAY mean that other parts of the document lose meaning, such as servers (unless used with overlays).

[webron]

I've added reusable Path Item objects as discussed.

We still need to review some additional changes regarding making paths optional.
For example:

A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification.

That is no longer accurate as a document now will no longer necessarily describe an API.

[darrelmiller]

We need to add the ability to reference a path item object from within callbacks and webhooks.

[darrelmiller]

Change

A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification.

to

A document (or set of documents) that defines or describes an API or elements of an API. The document MUST contain a paths object, a components object or a webhooks object. An OpenAPI definition uses and conforms to the OpenAPI Specification.

[tedepstein]

There's something that has never been quite clear to me: Suppose I have several files (or resources) that collectively describe a single API. One top-level file that defines the API overall, including its path items, and others that are collections of schemas, responses, and other reusable components. Is each of these physical files an OpenAPI document? Or do the files collectively comprise a single document?

It looks like the word "document" means both things:

1. Document as API Definition
   "A self-contained or multipartite resource which defines or describes an API..." sounds like it refers to a single logical API definition, possibly composed from multiple resources.
   
   
2. Document as Addressable Resource
   "...resource which defines or describes an API or elements of an API" sounds like it refers to any resource that includes any OpenAPI component.

@earth2marsh , IIRC, you first suggested the word "document" in a discussion thread that was debating "definition" vs. "description" vs. something else. At that time, I understood "document" to mean a physical file or addressable resource containing a valid OpenAPI Object. The document may define an actual API, having one or more Path Item Objects, and it may have any number of internal or external component references. Or it may be a library of components, with an empty Paths Object. But either way, it is a single resource.

If that's the definition, then shouldn't we have a different term to describe the composite, logical API description? Could we call that thing an "OpenAPI description" or "OpenAPI definition"? (Either is OK with me.)

OTOH, if document means the logical, self-contained or composite API definition, then should we use a different term for the individual resource(s)? Could each of those be an "OpenAPI resource" or "OpenAPI file" maybe?

As it stands, the word "document" seems to refer to both things, and this PR doesn't change that. The ambiguity can make it harder to talk about OpenAPI projects, and can lead to miscommunication.

Also, a small thing: I don't see the word "multipartite" very often. Interesting word. But would "composite" be a better choice for our target audience?

[earth2marsh]

The framing of A document (or set of documents) suggests to me that a document is like a resource. Whether an API is described using one or many documents, it can always be expressed as a fully-resolved single filed. This would be true in an overlay future, too. I have found that in common parlance, people (myself included) refer to that thing as "a spec". Myself, I just consider that Specification is referring to the class and spec is the instance, but I can understand why some folks are less comfortable with that.

Since my defeat in the great "definition" vs "description" wars, I have arrived at a better framing of why I preferred the latter term. When thinking about the phrase, "The menu is not the meal," it struck me that a spec is like the menu in how it describes what can be expected for a dish. Who has not been surprised to discover, either pleasantly or not, that the dish delivered to their table was unexpectedly different from what was in their mind when they ordered it?

FWIW, I prefer the "A document (or set of documents) that" phrasing, as it uses plainer language. "Multipartite" is an interesting new word I learned today, but I find it too abstruse for something that is already carrying a large cognitive load. :)

[MikeRalphson]

"Multipartite" is a perfectly cromulent word 😄 Perhaps it's more common in British English. I'll go with "composite" for now as 'a document is a document or set of documents' is a bit of an awkward / recursive definition.

[tedepstein]

@earth2marsh , thanks for the clarification and additional detail on "document." It sounds like it matches my second candidate meaning:

2. Document as Addressable Resource
   "...resource which defines or describes an API or elements of an API" sounds like it refers to any resource that includes any OpenAPI component.

So, could we use language that avoids the "document" self-reference, and makes it clear that an OAS document is a single physical resource, not a set of resources?

A resource that describes an API or elements of an API. The OpenAPI document MUST contain at least one paths field, a components field or a webhooks field. An OpenAPI document uses and conforms to the OpenAPI Specification.

It is also my understanding that an OpenAPI document must have an OpenAPI Object as its top-level element, and that OpenAPI Object is the thing that must contain one or more of these fields:

A resource that describes an API or elements of an API. The OpenAPI document MUST be a valid representation of an OpenAPI Object, containing at least one paths field, a components field or a webhooks field. An OpenAPI document uses and conforms to the OpenAPI Specification.

I assume that since we're talking about "fields" and their specific property names (paths, components, webhooks) as opposed to object types, a resource having only a Paths Object, Components Object, or Webhooks Object without the containing OpenAPI Object would not be considered an OAS document. Please correct me if I misunderstood.

[MikeRalphson]

@tedepstein I didn't want to repeat what was defined as REQUIRED elsewhere in the document, repetition can open the door to inconsistencies.

[tedepstein]

@MikeRalphson , I think you're referring to this sentence:

The OpenAPI document MUST contain at least one paths field, a components field or a webhooks field.

That wasn't my suggestion; it was introduced in commit 4836cce.

My only suggested changes were:

• Clarify the definition of a document as a single resource, not a collection of resources.
• Clarify that the requirement for a Paths, Components, or Webhooks object is just part of the requirement to be a valid OpenAPI Object.

If you want to remove the sentence about required fields altogether, then my last point is moot.

[earth2marsh]

Casing like pathItems would seem more aligned with securitySchemes and other compounds in the Spec, no?

[MikeRalphson]

👍

[earth2marsh]

If this is the first instance of "ACL", consider spelling out "Access Control List (ACL)" to help others who may not be familiar with the acronym.

[MikeRalphson]

Good spot.

[darrelmiller]

@OAI/tsc Please review so we can commit ASAP.

[earth2marsh]

LGTM