openapiredocly

How to enforce PascalCase for schema names in OpenAPI using Redocly?

I'm currently working on an OpenAPI 3.0.0 specification and using Redocly for validation. I have the following YAML file:

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0

components:
  schemas:
    MySchema:   
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

    my_schema: 
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

paths:
  /example:
    get:
      summary: Example endpoint
      responses:
        '200':
          description: Successful response

As you can see, I have two schema components defined: MySchema and my_schema. I want to enforce a naming convention where all schema names must be in PascalCase. I'm using Redocly to validate my OpenAPI specification, and I'm looking for a way to add a custom rule in the redocly.yaml configuration file that would enforce this convention.

Here’s my current redocly.yaml configuration:

extends:
  - recommended

rules:
  #disable
  operation-operationId:
    severity: off

  #warning
  security-defined:
    severity: off
  operation-summary:
    severity: off

Questions:

  1. How can I create a custom rule in Redocly to validate that all schema names are in PascalCase?
  2. Is there a built-in rule in Redocly that I can enable or configure to achieve this?
  3. If a custom rule is required, could you provide an example of how to define it in the redocly.yaml file?

I'm looking for a solution that can be applied across all components under components.schemas. Any guidance or examples would be greatly appreciated!

Solution

  • They have this example in their docs.

    https://redocly.com/docs/cli/rules/configurable-rules#casing-example

    You can extend that to other OpenAPI types they have defined, e.g. NamedSchemas

    You can see two examples, warn and error

    # redocly.yaml
rules:
  rule/named-examples-pascal-case:
    severity: error
    message: Must be PascalCase
    subject:
      type: NamedExamples
    assertions:
      casing: PascalCase
  rule/named-schemas-pascal-case:
    severity: warn
    message: Must be PascalCase
    subject:
      type: NamedSchemas
    assertions:
      casing: PascalCase

    openapi: 3.0.3
info:
  title: "thing"
  version: "0.0.1"
servers:
  - url: https://redocly.com
paths:
  "/thing":
    get:
      summary: a summary
      security: []
      operationId: getThing
      responses:
        "200":
          description: OK
          content:
            "application/json":
              schema:
                oneOf:
                  - $ref: "#/components/schemas/this_schema"
                  - $ref: "#/components/schemas/ThatSchema"
              examples:
                this:
                  $ref: "#/components/examples/this_example"
                that:
                  $ref: "#/components/examples/ThatExample"
components:
  schemas:
    this_schema:
      additionalProperties: false
      properties:
        this:
          type: string
    ThatSchema:
      additionalProperties: false
      properties:
        that:
          type: boolean
  examples:
    this_example:
      summary: this schema
      value: { "this": "1" }
    ThatExample:
      summary: this schema
      value: { "that": true }

    redocly test