rules.md

BetterCloud OAS Standard Rules

array-params-must-have-items-with-type (error)

Array parameters must have an items attribute with a type.

array-properties-must-have-items-with-type (error)

Array properties must have an items attribute with a type.

component-parameters-must-be-camel-case (error)

Component parameters must be camelCase.

component-parameters-must-have-meaningful-names (error)

Meaningful parameter names must be used in the form of {entity}Id, {entity}Description, {entity}Timestamp

component-parameters-must-include-examples (error)

Parameters must include examples.

component-schema-declarations-must-define-examples (error)

Every component schema declaration must define at least one example.

component-schema-enum-properties-must-be-upper-snake-case (error)

Enums must be all uppercase with underscores and must not end in an underscore.

component-schema-keys-must-be-pascal-case (error)

schema key must be PascalCase.

component-schema-parameters-must-be-camel-case (error)

Schema parameters must be camelCase.

component-schema-parameters-must-have-meaningful-description-names (error)

Meaningful schema description must be used in the form of {entity}Description. For example - customerDescription, userDescription.

component-schema-parameters-must-have-meaningful-id-names (error)

Meaningful schema Ids must be used in the form of {entity}Id. For example - customerId, betterCloudUserId

component-schema-parameters-must-have-meaningful-timestamp-names (error)

Meaningful schema timestamps must be used in the form of {entity}Timestamp. For example - createdTimestamp, updatedTimestamp

component-schema-parameters-must-have-meaningful-value-names (error)

Meaningful schema values must be used in the form of {entity}Value. For example - customerValue, displayValue

component-schema-properties-must-be-camel-case (error)

component schema properties must be camelCase.

component-schema-time-parameters-must-use-iso8601 (error)

Time must be represented using ISO8601

component-schemas-must-be-used (error)

Data object types must be used to specify the schema (data types) of a request response.

headers-must-include-examples (error)

Headers must include examples.

oas-files-must-have-contact-info (error)

Every API must have a contact containing name and email.

oas-files-must-have-global-description (error)

Every API must have a global description

oas-files-must-have-title-starting-with-bettercloud (error)

OAS Title must begin with "BetterCloud's". For example - BetterCloud's Automation API

oas-files-must-use-version-3.0.x (error)

OAS files must adhere to an openapi version of 3.0.x. All other versions are not authorized.

operation-ids-must-be-camel-case (error)

The operationId tags must be camelCase since some generators (sucha as RTK Query) don't support kebab-cases.

operationids-must-follow-naming-conventions (error)

The operationId tags must follow naming conventions for method.

path-actions-must-have-descriptions-and-summaries (error)

Every route of an API must have a description.

path-http-actions-must-be-limited (error)

http actions must be limited to get, put, post, delete, and patch

path-parameters-must-use-ref (error)

Query and Path parameters must use $ref for their schemas.

path-request-body-schemas-must-use-ref (error)

Endpoints with request bodies must use $ref for their schemas.

path-response-body-schemas-must-use-ref (error)

Response bodies no matter the response must use ref for their schemas.

path-responses-must-use-error-object-schema-for-errors (error)

When responding with a 4xx or 5xx, you must add and use the approved error response in the response schema

path-responses-must-use-qualified-status-codes (error)

You must only use allowed http response codes

paths-must-be-kebab-case (error)

All YAML/JSON paths must be kebab-case.

paths-must-have-descriptions (error)

Every route of an API must have a description.

paths-must-not-use-http-verbs-in-name (error)

The HTTP Verbs must not be used in the route path to define different actions on a resource.

paths-must-specify-tags (error)

Every route must specify at least one tag it belongs to.

response-parameters-must-be-camel-case (error)

Response parameters must be camelCase.

response-parameters-must-have-meaningful-description-names (error)

Meaningful response parameter timestamps must be used in the form of {entity}Description. For example - customerDescription, userDescription

response-parameters-must-have-meaningful-id-names (error)

Meaningful response parameter ids must be used in the form of {entity}Id. For example - customerId, betterCloudUserId

response-parameters-must-have-meaningful-timestamp-names (error)

Meaningful response parameter timestamps must be used in the form of {entity}Timestamp. For example - createdTimestamp, updatedTimestamp

response-parameters-must-have-meaningful-value-names (error)

Meaningful response parameter values must be used in the form of {entity}Value. For example - customerValue, displayValue

responses-must-be-wrapped-if-top-array (error)

Your responses must be wrapped

responses-must-contain-common-response-200-or-201 (error)

Responses must contain at least one 200-level response. For example - 200, 201

responses-must-contain-common-response-400 (error)

Responses must contain common response - 400 (Bad Request)

responses-must-contain-common-response-401 (error)

Responses must contain common response - 401 (Unauthorized)

responses-must-contain-common-response-403 (error)

Responses must contain common response - 403 (Forbidden)

responses-must-contain-common-response-404 (error)

Responses must contain common response - 404 (Not found)

responses-must-contain-common-response-406 (error)

Responses must contain common response - 406 (Not Acceptable)

responses-must-contain-common-response-415-for-post-and-put (error)

Responses must contain common response - 415 (Unsupported Media)

responses-must-contain-common-response-429 (error)

Responses must contain common response - 429 (Too many requests)

responses-must-contain-common-response-500 (error)

Responses must contain common response - 500 (Server error)

responses-must-return-response-body-with-2xx (error)

Every route returning a http status code of 200 or 201 must have a response body defined.

responses-must-use-media-type-json-content-type (error)

'application/json' is the only acceptable content type.

servers-must-match-api-standards (error)

Schema and host in URL must match company API standards.