如何解读包含properties关键字的OpenAPI数组定义？——对empty属性及渲染为有序映射的疑问

First off, let's clarify that this schema doesn't follow official OpenAPI specification rules—so the weird behavior you're seeing in Swagger Editor makes sense once you unpack what's going on.

1. How to interpret the empty property? #

In standard OpenAPI, type: array only pairs with array-specific keywords like items, minItems, maxItems, or uniqueItems. The properties keyword is exclusively for type: object schemas, where you define key-value attributes for an object.

That means the empty property here is a misplacement. If the original author wanted to indicate whether the array can be empty, the correct approach would be to use minItems: 0 (to allow empty arrays). If they needed an explicit boolean flag for empty state, they should wrap the array in a parent object instead:

UnitsContainer:
  type: object
  properties:
    empty:
      type: boolean
    units:
      type: array
      items:
        $ref: '#/components/schemas/Unit'

As written now, the empty property has no valid semantic meaning in the context of an array schema—it’s essentially a syntax error that Swagger Editor is trying to handle.

2. Why is it recognized as an ordered map? #

Swagger Editor is doing its best to render an invalid schema. Since standard arrays don’t support properties, when it sees both type: array and properties together, it falls back to displaying the structure as an ordered map (a key-value collection that preserves order).

An ordered map is the closest valid structure it can use—it can accommodate both the key-value pair (the empty property) and the ordered list of items (from the items field). This is basically the editor’s way of saying: "I don’t recognize this as a valid array, so I’ll show it as the most similar valid structure I know."

内容的提问来源于stack exchange，提问作者moverbk