Clarify [oas-types] rule: UpperCamelCase for all components

[pvdbosch]

Extend naming guidelines for data types [oas-types] (below) to cover all definitions of components (responses, requestBodies, ...)

Rule: Naming of data types [oas-types] Data type names SHOULD be defined in American English and use UpperCamelCase notation. For abbreviations as well, all letters except the first one should be lowercased.

Do not use underscores (_), hyphens (-) or dots (.) in a data type name, nor use a digit as first letter.

Overly generic terms like info(rmation) and data SHOULD NOT be used as data type name or part of it.

[pvdbosch]

WG is OK to update the rule, I'll work out PR.

[pvdbosch]

PR #172 ready for review

[jpraet]

So this also applies to securitySchemes, right?

We currently have this:

components:
  securitySchemes:
    oauth-socsec:
      type: oauth2
      description: access using access token retrieved from oauth2 server
      flows:
        clientCredentials:
          tokenUrl: https://placeholder.socialsecurity.be/oauth2endpoint
          scopes:
            "scope:cbss:api:foreignLegalEntity:consult": consult foreign legal entities
            "scope:cbss:api:monitoring": access to health check operation
security:
  - oauth-socsec:
      - scope:cbss:api:foreignLegalEntity:consult
      - scope:cbss:api:monitoring

[pvdbosch]

Indeed. That seems to be the place where a lot of OpenAPI files are not compliant yet, but I can't see a reason why it should be an exception. UpperCamelCase makes it clearer that it's a referenced component.

FYI, I also requested to add a verification to the styleguide validator that the references to the securitySchemes from the "security" definitions (Security Requirement Objects) are correct, bc that's something a lot of editors don't seem to check even though part of the OpenAPI spec.

[jpraet]

Name of security schemes defined in SMALS / eHealth / CBSS APIs often start with oauth.

For oauth-socsec example above this becomes OauthSocSec? OAuthSocSec is currently not allowed:

[ERROR] file: openapi.yaml: ln 439: [MANDATORY] [oas-types] Component names SHOULD use UpperCamelCase notation. For abbreviations as well, all letters except the first one should be lowercased. /components/securitySchemes/OAuthSocSec

[pvdbosch]

Indeed only OauthSocSec works.

You could argue whether the guideline applies for "abbreviations: all letters after the first should be lowercase". "OAuth" is short for "Open Authorization" but is it a single abbreviation or two separate ones? The validator can't distinguish a single-letter word or abbreviation though from a real violation.

PR has been merged and will be published next release.