Sorting

Sort OpenAPI fields in a defined order. Fields not specified keep their original order.

CLI Usage

Terminal

# Sort with defaults
npx openapi-format openapi.json -o openapi-sorted.json

# Sort with custom ordering
npx openapi-format openapi.json -o openapi-sorted.json --sortFile customSort.json

# Skip sorting entirely
npx openapi-format openapi.json -o output.json --no-sort

Default Sort Fields

The default sort order is stored in defaultSort.json. You can override it by providing a custom sort file.

Key	Ordered by
root	openapi → info → servers → paths → components → tags → x-tagGroups → externalDocs
get / post / put / patch / delete	operationId → summary → description → parameters → requestBody → responses
parameters	name → in → description → required → schema
requestBody	description → headers → content → links
responses	description → headers → content → links
content	By alphabet
components	parameters → schemas
schema / schemas	description → type → items → properties → format → example → default
properties	description → type → items → format → example → default → enum

Custom Sort File

Create a JSON or YAML file specifying your preferred field order per key:

customSort.json

{
  "root": ["openapi", "info", "servers", "paths", "components"],
  "get": ["summary", "description", "operationId", "parameters", "responses"],
  "schema": ["type", "description", "properties", "required"]
}

Sort Paths

Control the order of paths in your OpenAPI document using sortPathsBy:

Option	Description
original	Keep the original order (default)
path	Order alphabetically by path
tags	Order by the first tag of the first method

Sort Components

Sort items within the components section alphabetically:

Terminal

npx openapi-format openapi.json -o output.json --sortComponentsFile sortComponents.json

sortComponents.json

["schemas", "parameters", "headers", "requestBodies", "responses", "securitySchemes"]

Example

Before

components:
  schemas:
    Order:
      type: object
    Customer:
      type: object
    Address:
      type: object

After

components:
  schemas:
    Address:
      type: object
    Customer:
      type: object
    Order:
      type: object

Sort Component Properties

Sort properties within schema components alphabetically:

Terminal

npx openapi-format openapi.json -o output.json --sortComponentsProps

Before

schemas:
  UserDto:
    type: object
    properties:
      lastName:
        type: string
      firstName:
        type: string

After

schemas:
  UserDto:
    type: object
    properties:
      firstName:
        type: string
      lastName:
        type: string