Formatting & Casing

Enforce consistent casing across operationIds, properties, parameters, and component keys.

CLI Usage

Terminal

npx openapi-format openapi.json -o output.json --casingFile customCasing.yaml

Casing Types

Type	Alias	Example
camelCase	camelCase	openapiFormat
PascalCase	PascalCase	OpenapiFormat
kebab-case	kebabCase	openapi-format
Train-Case	TrainCase	Openapi-Format
snake_case	snakeCase	openapi_format
Ada_Case	AdaCase	Openapi_Format
CONSTANT_CASE	constantCase	OPENAPI_FORMAT
COBOL-CASE	cobolCase	OPENAPI-FORMAT
Dot.notation	dotNotation	openapi.format
Space case	spaceCase	openapi format
Capital Case	capitalCase	Openapi Format
lower case	lowerCase	openapi format
UPPER CASE	upperCase	OPENAPI FORMAT

Casing Options

Key	Description
operationId	Operation IDs in the Operations Object
properties	Schema property keys (inline & components)
parametersQuery	Query parameter names
parametersHeader	Header parameter names
parametersPath	Path parameter names
parametersCookie	Cookie parameter names
componentsSchemas	Schema model keys & $ref links
componentsExamples	Example model keys & $ref links
componentsHeaders	Header model keys & $ref links
componentsResponses	Response model keys & $ref links
componentsRequestBodies	Request body model keys & $ref links
componentsSecuritySchemes	Security scheme keys & $ref links
componentsParametersQuery	Query parameter component keys
componentsParametersHeader	Header parameter component keys
componentsParametersPath	Path parameter component keys
componentsParametersCookie	Cookie parameter component keys

Full Configuration Example

customCasing.yaml

operationId: snake_case
properties: camelCase

parametersQuery: kebab-case
parametersHeader: kebab-case
parametersPath: snake_case

componentsExamples: PascalCase
componentsSchemas: camelCase
componentsHeaders: kebab-case
componentsResponses: snake_case
componentsRequestBodies: snake_case
componentsSecuritySchemes: PascalCase

componentsParametersQuery: snake_case
componentsParametersHeader: kebab-case
componentsParametersPath: camelCase

Example: operationId

casing.yaml

operationId: kebab-case

Open Example in Playground

Before

paths:
  /pets:
    get:
      operationId: getPets
  /pets/{petId}:
    get:
      operationId: getPetById
    delete:
      operationId: deletePet

After

paths:
  /pets:
    get:
      operationId: get-pets
  /pets/{petId}:
    get:
      operationId: get-pet-by-id
    delete:
      operationId: delete-pet

Example: Schema Properties

casing.yaml

properties: snake_case

Open Example in Playground

Before

components:
  schemas:
    UserModel:
      type: object
      properties:
        id:
          type: integer
          example: 10
        emailAddress:
          type: string
          example: [email protected]
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Doe

After

components:
  schemas:
    UserModel:
      type: object
      properties:
        id:
          type: integer
          example: 10
        email_address:
          type: string
          example: [email protected]
        first_name:
          type: string
          example: John
        last_name:
          type: string
          example: Doe

Example: Component Keys

casing.yaml

componentsSchemas: PascalCase

Open Example in Playground

Before

paths:
  /orders:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order-model'
components:
  schemas:
    userModel:
      type: object
    order-model:
      type: object
    pet_model:
      type: object

After — keys + $ref links updated

paths:
  /orders:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderModel'
components:
  schemas:
    UserModel:
      type: object
    OrderModel:
      type: object
    PetModel:
      type: object

Example: Parameter Names

casing.yaml

parametersPath: kebab-case
parametersQuery: snake_case

Open Example in Playground

Before

paths:
  /pet/{petId}:
    get:
      parameters:
        - name: petId
          in: path
          description: ID of pet to return
        - name: includeDetails
          in: query
          description: Include full details
        - $ref: '#/components/parameters/LimitParam'
components:
  parameters:
    LimitParam:
      name: limitParam
      in: query

After

paths:
  /pet/{petId}:
    get:
      parameters:
        - name: pet-id
          in: path
          description: ID of pet to return
        - name: include_details
          in: query
          description: Include full details
        - $ref: '#/components/parameters/LimitParam'
components:
  parameters:
    LimitParam:
      name: limit_param
      in: query

keepCharacter

Use *keepCharacter to preserve a character while casing is normalized. This is useful when you want the formatter to keep a separator that is already part of your naming convention instead of removing it during the conversion.

KeepChars Options

Key	Description
operationIdKeepChars	Impacts `operationId` values in operations.
propertiesKeepChars	Impacts schema property keys.
parametersQueryKeepChars	Impacts query parameter names.
parametersHeaderKeepChars	Impacts header parameter names.
parametersPathKeepChars	Impacts path parameter names.
parametersCookieKeepChars	Impacts cookie parameter names.
componentsSchemasKeepChars	Impacts `components.schemas` keys.
componentsExamplesKeepChars	Impacts `components.examples` keys.
componentsHeadersKeepChars	Impacts `components.headers` keys.
componentsResponsesKeepChars	Impacts `components.responses` keys.
componentsRequestBodiesKeepChars	Impacts `components.requestBodies` keys.
componentsSecuritySchemesKeepChars	Impacts `components.securitySchemes` keys.
componentsParametersQueryKeepChars	Impacts reusable query parameter keys in `components.parameters`.
componentsParametersHeaderKeepChars	Impacts reusable header parameter keys in `components.parameters`.
componentsParametersPathKeepChars	Impacts reusable path parameter keys in `components.parameters`.
componentsParametersCookieKeepChars	Impacts reusable cookie parameter keys in `components.parameters`.

Keep characters are merged with the default preserved characters that openapi-format already keeps: $ and @. To disable the default preserved characters for direct changeCase usage, pass an empty array as the custom keep characters.

Example: Keep Character

The example below keeps dots in selected fields so you can preserve version suffixes and nested names while still applying casing to the rest of the identifier.

casing.yaml

operationId: snake_case
operationIdKeepChars:
  - .

properties: camelCase
propertiesKeepChars:
  - .

parametersQuery: camelCase
parametersQueryKeepChars:
  - .

parametersHeader: kebab-case
parametersPath: snake_case

componentsExamples: PascalCase

componentsSchemas: PascalCase
componentsSchemasKeepChars:
  - .

componentsHeaders: kebab-case
componentsResponses: snake_case
componentsRequestBodies: snake_case
componentsSecuritySchemes: PascalCase

componentsParametersQuery: snake_case
componentsParametersQueryKeepChars:
  - .
componentsParametersHeader: kebab-case
componentsParametersPath: camelCase

Open Example in Playground

Before

paths:
  /users/{userId}:
    get:
      operationId: getUser.v1
      parameters:
        - name: cursor.created_at
          in: query
          description: Pagination cursor
        - name: pageSize.v1
          in: query
          description: Page size hint
components:
  schemas:
    Pet.v1:
      type: object
      properties:
        account_id.v2:
          type: string
  parameters:
    LimitPageParam:
      name: pageSize.v1
      in: query

After

paths:
  /users/{userId}:
    get:
      operationId: get_user.v_1
      parameters:
        - name: cursor.createdAt
          in: query
          description: Pagination cursor
        - name: pageSize.v1
          in: query
          description: Page size hint
components:
  schemas:
    Pet.V1:
      type: object
      properties:
        accountId.v2:
          type: string
  parameters:
    limit_page_param:
      name: pageSize.v1
      in: query