Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make paths object optional #1781

Merged
merged 7 commits into from
Mar 19, 2020
Merged

Make paths object optional #1781

Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0ba7343
Make paths object optional
MikeRalphson Dec 18, 2018
b39dbdf
Merge branch 'v3.1.0-dev' into paths-optional
webron Jan 23, 2020
efaf094
Adding reusable Path Item Objects
webron Jan 23, 2020
4836cce
Adopt DM's suggested change to OpenAPI doc definition
MikeRalphson Jan 30, 2020
bfcaa37
Cleanup use of specification and definition where we mean document
MikeRalphson Jan 30, 2020
4754b94
multipartite>composite, define ACL
MikeRalphson Feb 14, 2020
9073629
Add ' | Reference Object' to callbacks/webhooks
MikeRalphson Feb 19, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 16 additions & 13 deletions versions/3.1.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ An OpenAPI definition can then be used by documentation generation tools to disp
## Definitions

##### <a name="oasDocument"></a>OpenAPI Document
A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification.
A self-contained or multipartite resource which defines or describes an API or elements of an API. The OpenAPI document MUST contain at least one [paths](#pathsObject) field, a [components](#oasComponents) field or a [webhooks](#oasWebhooks) field. An OpenAPI document uses and conforms to the OpenAPI Specification.
Copy link
Contributor

@tedepstein tedepstein Jan 31, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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. :)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


##### <a name="pathTemplating"></a>Path Templating
Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters.
Expand Down Expand Up @@ -183,7 +183,7 @@ In the following description, if a field is not explicitly **REQUIRED** or descr

#### <a name="oasObject"></a>OpenAPI Object

This is the root document object of the [OpenAPI document](#oasDocument).
This is the root object of the [OpenAPI document](#oasDocument).

##### Fixed Fields

Expand All @@ -192,11 +192,11 @@ Field Name | Type | Description
<a name="oasVersion"></a>openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](https://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string.
<a name="oasInfo"></a>info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required.
<a name="oasServers"></a>servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`.
<a name="oasPaths"></a>paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API.
<a name="oasPaths"></a>paths | [Paths Object](#pathsObject) | The available paths and operations for the API.
<a name="oasWebhooks"></a>webhooks | Map[`string`, [Path Item Object](#pathItemObject)] | The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the `callbacks` feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](../examples/v3.1/webhook-example.yaml) is available.
<a name="oasComponents"></a>components | [Components Object](#componentsObject) | An element to hold various schemas for the specification.
<a name="oasComponents"></a>components | [Components Object](#componentsObject) | An element to hold various schemas for the document.
<a name="oasSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition.
<a name="oasTags"></a>tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.
<a name="oasTags"></a>tags | [[Tag Object](#tagObject)] | A list of tags used by the document with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.
<a name="oasExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation.


Expand Down Expand Up @@ -458,6 +458,8 @@ Field Name | Type | Description
<a name="componentsSecuritySchemes"></a> securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject).
<a name="componentsLinks"></a> links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Link Objects](#linkObject).
<a name="componentsCallbacks"></a> callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Callback Objects](#callbackObject).
<a name="componentsPathitems"></a> pathitems | Map[`string`, [Path Item Object](#pathItemObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Path Item Object](#pathItemObject).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍


This object MAY be extended with [Specification Extensions](#specificationExtensions).

Expand Down Expand Up @@ -651,7 +653,7 @@ components:
#### <a name="pathsObject"></a>Paths Object

Holds the relative paths to the individual endpoints and their operations.
The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [ACL constraints](#securityFiltering).
The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [ACL constraints](#securityFiltering). Paths MAY be omitted in some classes of OAS documents, including referenced sub-documents and overlays.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good spot.


##### Patterned Fields

Expand Down Expand Up @@ -1641,10 +1643,11 @@ The documentation is not necessarily expected to cover all possible HTTP respons
However, documentation is expected to cover a successful operation response and any known errors.

The `default` MAY be used as a default response object for all HTTP codes
that are not covered individually by the specification.
that are not covered individually by the `Responses Object`.

The `Responses Object` MUST contain at least one response code, and it
SHOULD be the response for a successful operation call.
The `Responses Object` MUST contain at least one response code, and if only one
response code is provided it SHOULD be the response for a successful operation
call.

##### Fixed Fields
Field Name | Type | Description
Expand Down Expand Up @@ -2045,7 +2048,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens
A linked operation MUST be identified using either an `operationRef` or `operationId`.
In the case of an `operationId`, it MUST be unique and resolved in the scope of the OAS document.
Because of the potential for name clashes, the `operationRef` syntax is preferred
for specifications with external references.
for OpenAPI documents with external references.

##### Examples

Expand Down Expand Up @@ -2241,7 +2244,7 @@ description: Pets operations

#### <a name="referenceObject"></a>Reference Object

A simple object to allow referencing other components in the specification, internally and externally.
A simple object to allow referencing other components in the OpenAPI document, internally and externally.

The Reference Object is defined by [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) and follows the same structure, behavior and rules.

Expand Down Expand Up @@ -2671,7 +2674,7 @@ components:

#### <a name="discriminatorObject"></a>Discriminator Object

When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation. The discriminator is a specific object in a schema which is used to inform the consumer of the specification of an alternative schema based on the value associated with it.
When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation. The discriminator is a specific object in a schema which is used to inform the consumer of the document of an alternative schema based on the value associated with it.

When using the discriminator, _inline_ schemas will not be considered.

Expand Down Expand Up @@ -3390,7 +3393,7 @@ While not part of the specification itself, certain libraries MAY choose to allo

Two examples of this:

1. The [Paths Object](#pathsObject) MAY be empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They'd still have access to the [Info Object](#infoObject) which may contain additional information regarding authentication.
1. The [Paths Object](#pathsObject) MAY be present but empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They would still have access to at least the [Info Object](#infoObject) which may contain additional information regarding authentication.
2. The [Path Item Object](#pathItemObject) MAY be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different than hiding the path itself from the [Paths Object](#pathsObject), so the user will not be aware of its existence. This allows the documentation provider to finely control what the viewer can see.

## <a name="revisionHistory"></a>Appendix A: Revision History
Expand Down