Openapi-specification: Make Paths Object Optional

[tedepstein]

The Paths Object is required to be present in the OpenAPI Object.

This makes it awkward to create an OpenAPI spec that serves as a "catalog" of reusable components. This is already a common usage pattern in OpenAPI 2.0, and we expect it will be even more common with OpenAPI 3.0, with the introduction of the Components Object, and new types of reusable definitions contained within it.

It's possible to create a catalog file, but you have to do one of two things:

1. Use JSON's empty object syntax, because there is no explicit empty object syntax in YAML. This works, but it's awkward, and is just a way of getting around the requirement. to have a Paths Object. Here's a 2.0 example:

swagger: "2.0"
info:
  version: 1.0.0
  title: Uber Schema Definitions

# This is a component file, used by the Uber API specification. 
# The paths property is required, so we use curly braces to denote an empty object,
# meaning there are no path items defined in this file. 
paths: {}

# The definitions section contains a set of named Schema Objects. Each object
# describes a reusable data type. We refer to these using a $ref property, with a 
# JSON Reference value that resolves to the definition.
definitions:

  PriceEstimate:
    type: object
    properties:
      product_id:
        type: string
        description: Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles
  ...

OR...

1. Use a YAML or JSON file format that is not valid OpenAPI, specifically for catalog files. This means the file can't be processed by standard OpenAPI documentation tools, code generators and other processors, if those tools include schema validation (or the equivalent). And it means we don't have an implementation-independent standard format for catalog files.

So I would argue for making paths optional.

[webron]

This is actually not different than 2.0. The spec is intended to document APIs, not catalogs of reusable objects. We can change that definition, but that's what it is. A file without paths does not describe an API.

The reason why paths may be empty is explained in the spec (otherwise, we would have enforced at least one path).

If you want to create a catalog, the only part of the spec you really need is the components, however, 'external' references don't have to adhere to the same structure of the spec (for several reasons).

[tedepstein]

This is actually not different than 2.0. The spec is intended to document APIs, not catalogs of reusable objects. We can change that definition, but that's what it is. A file without paths does not describe an API.

Well, here's what's weighing against that distinction:

• Component catalogs are a common usage pattern, encouraged and supported by multiple API design tools, ours included.
• You can effectively repurpose the OpenAPI format as a component catalog, simply by adding two characters (open+close curly brace).
• There's a significant advantage to having all of the OpenAPIs editing machinery (validation, content assist, etc.) available when editing component catalogs, just as with a full, valid API description.
• There's a significant advantage to having a standard component catalog format that is portable across tools.

So the question is, what's the value of requiring the Paths object?

• If the goal is to make sure that an OpenAPI spec actually describes an API, I would say that requiring Paths doesn't achieve that, because it can still be empty.
• The distinction between an empty Paths object and an omitted Paths object might have some meaning in the ACL use case you mentioned. But making Paths optional would still allow for this, and maybe even make it more explicit. Empty Paths object means, "This API has paths, but I'm not telling you what they are." Omitted Paths object means, "This OpenAPI spec, for whatever reason, doesn't define any paths. It probably doesn't describe an API at all. Look elsewhere." So the presence of an empty Paths object is potentially _more meaningful_ because there's an alternative representation for non-API spec files.
• IMO, it's hard to see any "slippery slope" that we'd be sliding down if we made Paths optional. It's already effectively optional just by adding a bit of awkward syntax.

Please correct me if you really think those two curly braces are the only thing keeping this Pandora's box from unleashing eternal chaos. And of course I can live with it as-is. I'm just having a hard time seeing a downside to this.

[webron]

Again, this is about repurposing the spec. It's meant to describe APIs, not catalogs of objects that can be used in APIs. The paths is not the only required items that is not necessarily important, the info can impose unnecessary things as well. And what would be the meaning of a combination of just servers and components?

The components is meant as a convenience. We could have said just as well that you can only reference definitions outside an API definition (and I'm not suggesting that).

I disagree with your point about the ACL. A non-existing paths would tell me this is a broken API definition, not a filtered one.

I get the benefits of using a similar structure. However, I feel we should revisit it only after the upcoming release. If other @OAI/tdc members feel differently, please say so.

[CharlieReitzel]

The simple approach, I think, is to define components in separate source files that hew to the mutually supported subset of JSON Schema and refer to these schema elements from my Open API documents as needed.

However, this discussion has clarified an issue for me. Consider the relationship between WSDL and XML Schema. WSDL is an XML vocabulary that describes services (requests w/ responses). When WSDL needs to define the contents of request or response bodies, it does so by incorporating the XML Schema standard _by reference_.

Contrast this the relationship between Open API and JSON Schema. In essence, Open API _includes_ and _restricts_ (and, occasionally, alters!) JSON Schema. And this is where it goes wrong, imo. Open API needs to "suck it up" and deal with entire JSON Schema spec - at least for any schema definitions an API author needs.

It took a while for XML Schema tooling to get all the way there. But it's been there for years and it works well. By splintering the schema spec between Open API and JSON Schema proper, it is actually slowing down progress on tooling and making it more difficult to define APIs out of re-usable components (does anyone _not_ do that?!?).

[darrelmiller]

deal with entire JSON Schema spec - at least for any schema definitions an API author needs.

Welcome to 4 years of debating what that includes ,while JSON Schema goes through multiple revisions. There are a bunch of people trying to make happen what you are suggesting but it involves trade-offs that different people have different opinions about.

[handrews]

@CharlieReitzel but we're getting closer! @philsturgeon refers to this as the "superset-subset" problem. The draft of JSON Schema that will come out this month (seriously- I've put up some of the last few JSON Schema spec PRs today, just need to add some better examples now) allows defining extension vocabularies and restricting usage in machine-readable ways.

As @darrelmiller knows, we (myself and @philsturgeon) are now working with the TSC and others (hi @mkistler!) on how this could be used with OpenAPI.

In fairness to the OpenAPI folks, JSON Schema was practically abandoned for most of the time while OAS 3 was being developed, and while it had been revived into active development shortly before OAS 3.0 was published, we had not gotten far enough along to help converge things and OAS 3.0 rightly chose not to wait on what was then a relatively untested new JSON Schema spec team. We've made a lot of progress on both projects since then and I am optimistic about OAS 3.1 and JSON Schema draft 2019-08 working together much more smoothly.

[CharlieReitzel]

@darrelmiller @handrews I understand that what I'm asking for is much (much!) easier said than done. All the hard work, which includes all the discussion and consensus building, is very much appreciated.

I _like_ schema and contract based development. So I'm a big fan of what you all are doing.

[hkosova]

In OAS 3.1, paths are optional.

https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0-rc0

An OpenAPI Document now requires at least one of paths, components or webhooks to exist at the top level. While previous versions required paths, now a valid OpenAPI Document can describe only webhooks, or even only reusable components.

Can this be closed?

[philsturgeon]

It can be! 🎊

[shefaliv]

@hkosova In order to leverage this, do I update the yml file to include "openapi: 3.1.0"? The samples in this repo seem to be quite outdated, so I'm not sure what example to use. 3.1.0 doesn't seem to be allowed in the 5.0.0-beta JAR file or the version installed via brew.

[philsturgeon]

3.1.0 is currently a release candidate and not much tooling (any?) supports it yet. When it’s released, you’ll need to change the version at the top yes and paths will be optional.