Make Paths Object Optional

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.

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

[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?