naming.yml

#
# Naming convention hints
#
# $..parameters.[?(@.name && @.name.match("^(nome|cognome|name|surname|cf|fiscalcode)$",i))]
rules:
  use-recommended-names-in-parameters: &use-recommended-names
    description: |-
      Use well defined parameter and schema names, deriving them
      from the national ontologies available at https://w3id.org/italia/onto/

      For example, you can model a person using the following names:
      
      ```
      {
        "en": {
          "given_name": "Mario",
          "family_name": "Rossi",
          "tax_code": "12345678901"
        },
        "it": {
          "nome_proprio": "Mario",
          "cognome": "Rossi",
          "codice_fiscale": "12345678901"
        }
      }
      ```


    message: |-
      Use recommended variable names in {{value}}.
    formats:
      - oas3
    severity: info
    given: >-
      $..parameters.[?(@.name && @.name.match && @.name.match(/^(nome|name|surname|cf|fiscal_?code|fiscal_?number|first_?name|last_?name)$/i) )]
    then:
      field: "name"
      function: pattern
      functionOptions:
        match: //
  use-recommended-names-in-schemas:
    <<: *use-recommended-names
    given: '$..[?(@ && @.type=="object")].properties.[?(
       @property 
       && @property.match 
       && @property.match(/^(nome|name|surname|cf|fiscal_?code|fiscal_?number|first_?name|last_?name)$/i)
      )]'
    then:
      field: "@key"
      function: pattern
      functionOptions:
        match: //
  no-method-name-in-operationId:
    description: |-
      Avoid using method names in `operationId`s because it couples
      the API design with the implementation.

      An operation that edits an entry can be published with different methods,
      for example either POST, PUT or PATCH, and while evolving the API
      you could decide to associate an operationId with another method.

      You can use for example

      ```
      openapi: 3.0.1
      ...
      paths:
        /entries:
          get:
            operationId: list_entries
          post:
            operationId: create_entry
        /entries/{id}:
          put:
            operationId: upsert_entry
          patch:
            operationId: edit_entry
      ```
      
    message: |-
      Avoid using method names in operationIds.
    formats:
      - oas3
    severity: hint
    given: >-
      $..[?(@.operationId && @.operationId.match && @.operationId.match(/^(get|post|put|delete|patch|head)/i) )]
    then:
      field: "operationId"
      function: pattern
      functionOptions:
        match: //