Skip to main content

Standard Rules

Common rules for building Basketry pipelines. These rules may be used with any Basketry parser and may be combined with any other Basketry rules.

Install

npm install @basketry/rules

Basic Usage

basketry.config.json
{
"source": "petstore.json",
"parser": "@basketry/openapi-3",
"rules": [
"@basketry/rules/lib/array-parameter-length",
"@basketry/rules/lib/description",
"@basketry/rules/lib/http-status",
"@basketry/rules/lib/relay-pagination",
"@basketry/rules/lib/string-id"
]
}

Included Rules

Descriptions

Rule
@basketry/rules/lib/method-descriptionRequires all methods to have a description
@basketry/rules/lib/parameter-descriptionRequires all method parameters to have a description
@basketry/rules/lib/property-descriptionRequires all type properties to have a description
@basketry/rules/lib/type-descriptionRequires all types to have a description
@basketry/rules/lib/descriptionCombines all of the other description rules

Options

By default, violations of these rules will be displayed as errors. This may be overridden with the severity option:

{
"rules": [
{
"rule": "@basketry/rules/lib/description",
"options": { "severity": "warning" }
}
]
}

Array parameter length

Rule
@basketry/rules/lib/array-parameter-lengthRequires method array-typed parameters to specify max item lengths.

Options

By default, violations of this rule will be displayed as errors. This may be overridden with the severity option:

{
"rules": [
{
"rule": "@basketry/rules/lib/array-parameter-length",
"options": { "severity": "warning" }
}
]
}

HTTP status codes

Rule
@basketry/rules/lib/http-delete-statusRequires that HTTP DELETE status codes must be 200, 202, or 204
@basketry/rules/lib/http-get-statusRequires that HTTP GET status codes must be 200, 204, or 206
@basketry/rules/lib/http-patch-statusRequires that HTTP PATCH status codes must be 200, 202, or 204
@basketry/rules/lib/http-post-statusRequires that HTTP POST status codes must be 200, 201, 202, or 204
@basketry/rules/lib/http-put-statusRequires that HTTP PUT status codes must be 200, 201, 202, or 204
@basketry/rules/lib/http-no-content-statusRequires methods with no return type return status code of 204 AND that methods that do return data do not return 204
@basketry/rules/lib/http-statusCombines all of the other HTTP status code rules

Options

By default, violations of these rules will be displayed as errors. This may be overridden with the severity option:

{
"rules": [
{
"rule": "@basketry/rules/lib/http-status",
"options": { "severity": "warning" }
}
]
}

Pagination

Rule
@basketry/rules/lib/offset-paginationRequires methods that return arrays define offest and limit paremters
@basketry/rules/lib/relay-paginationRequires methods that return arrays define Relay-style pagination paremters and also return a "page info" object

Options

By default, violations of these rules will be displayed as errors. This may be overridden with the severity option. This rule allows for both bare array and envelope object return types. By default, the payload is expected to be in a property called value, values, or data. These expectations may be overridden with the payload option.

If there is HTTP protocol information defined for this method, then the rules are only applied to HTTP GET methods. This may be overridden with the verb or verbs option.

{
"rules": [
{
"rule": "@basketry/rules/lib/offset-pagination",
"options": {
"severity": "warning",
"payload": ["result", "results"],
"verbs": ["GET", "POST"]
}
}
]
}

To apply the rule selectively, use an allow/deny list with method names.

In the following example, the rule will only be enforced on myPaginatedMethod. The pagination rule will not be enforced on any method not in the allow list.

{
"rules": [
{
"rule": "@basketry/rules/lib/offset-pagination",
"options": { "allow": ["myPaginatedMethod"] }
}
]
}

In the following example, the rule will not be enforced on myUnpaginatedMethod. The pagination rule will be enforced on all methods not in the deny list.

{
"rules": [
{
"rule": "@basketry/rules/lib/offset-pagination",
"options": { "deny": ["myUnpaginatedMethod"] }
}
]
}

Simultaneous usage of both allow and deny lists may lead to unpredictable results.

String IDs

Rule
@basketry/rules/lib/string-idRequires that type properties named id must be of type string

Options

By default, violations of this rule will be displayed as errors. This may be overridden with the severity option:

{
"rules": [
{
"rule": "@basketry/rules/lib/string-id",
"options": { "severity": "warning" }
}
]
}

Response envelopes

Rule
@basketry/rules/lib/response-envelopeRequires that all methods return envelope objects that contain both an errors array and a payload property.

Options

By default, violations of these rules will be displayed as errors. This may be overridden with the severity option. This rule allows for both bare array and evelope object return types. By default, the payload is expected to be in a property called value, values, or data. These expectations may be overridded with the payload option. Note that other rules may enforce various pluralization requirements, so be sure to include both the plural and singular form of your payload name.

{
"rules": [
{
"rule": "@basketry/rules/lib/response-envelope",
"options": {
"severity": "warning",
"payload": ["result", "results"]
}
}
]
}

Object Bodies

Rule
@basketry/rules/lib/object-request-bodyRequires that request bodies (if defined) be objects or unions of objects.
@basketry/rules/lib/object-response-bodyRequires that response bodies (if defined) be objects or unions of objects.
@basketry/rules/lib/object-bodyCombines all of the other object body rules.

Options

By default, violations of these rules will be displayed as errors. This may be overridden with the severity option.

{
"rules": [
{
"rule": "@basketry/rules/lib/object-body",
"options": { "severity": "warning" }
}
]
}

No Disallowed HTTP Bodies

The HTTP/1.1 specification (RFC 7231) either prohibits bodies or does not define body behavior for certain HTTP methods. In these cases, certain systems may ignore, reject, or fail if a body is provided. The following rules prohibit bodies from being defined for those HTTP methods.

Rule
@basketry/rules/lib/no-http-delete-bodyProhibits HTTP DELETE methods from defining a request body.
@basketry/rules/lib/no-http-get-bodyProhibits HTTP GET methods from defining a request body.
@basketry/rules/lib/no-http-head-bodyProhibits HTTP HEAD methods from defining a request body.
@basketry/rules/lib/no-http-options-bodyProhibits HTTP OPTIONS methods from defining a request body.
@basketry/rules/lib/no-http-trace-bodyProhibits HTTP TRACE methods from defining a request body.
@basketry/rules/lib/no-disallowed-http-bodyCombines all of the other disallowed HTTP body rules.

Options

By default, violations of these rules will be displayed as errors. This may be overridden with the severity option.

{
"rules": [
{
"rule": "@basketry/rules/lib/no-disallowed-http-body",
"options": { "severity": "warning" }
}
]
}

No Null Properties

Rule
@basketry/rules/lib/no-null-propertiesRequires that properties may not be null. When this rule is applied, properties may still be optional.

Options

By default, this rule is applied to all properties for all input and output types. This may be overridden with the allowHttpVerbs option to allow input types for certain HTTP verbs to be exempt from this rule.

{
"rules": [
{
"rule": "@basketry/rules/lib/no-null-properties",
"options": { "allowHttpVerbs": ["PATCH"] }
}
]
}

By default, violations of this rule will be displayed as errors. This may be overridden with the severity option.

{
"rules": [
{
"rule": "@basketry/rules/lib/no-null-properties",
"options": { "severity": "warning" }
}
]
}

Pluralization

Rule
@basketry/rules/lib/enum-pluralizationRequires that enums have singular names.
@basketry/rules/lib/parameter-pluralizationRequires that array parameters have pluralized names and non-array parameters have singular names.
@basketry/rules/lib/property-pluralizationRequires that array properties have pluralized names and non-array properties have singular names.
@basketry/rules/lib/pluralizationCombines all of the other pluralization rules

Options

By default, violations of this rule will be displayed as errors. This may be overridden with the severity option:

{
"rules": [
{
"rule": "@basketry/rules/lib/pluralization",
"options": { "severity": "warning" }
}
]
}

Casing

Rule
@basketry/rules/lib/casingDefines casing requirements for the various parts of a service

Options

Casing values must be one of the following:

  • snake - eg. some_item_name
  • pascal - eg. SomeItemName
  • camel - eg. someItemName
  • kebab - eg. some-item-name
  • header - eg. Some-Item-Name
  • constant - eg. SOME_ITEM_NAME

Any other casing value will be silently ignored.

The following opitons may be used to enforcing casing rules within the service:

  • enum
  • enumValue
  • path
  • method
  • parameter
  • query
  • header
  • property
  • type

Note that if query or header are supplied when parameter is also supplied, then the more specific rules for headers and query parameters will override the setting for all other parameters. If query or header are not supplied, the the value for parameter will also be used for headers and query parameters.

By default, violations of this rule will be displayed as errors. This may be overridden with the severity option.

{
"rules": [
{
"rule": "@basketry/rules/lib/casing",
"options": {
"severity": "warning",
"enum": "camel",
"enumValue": "constant",
"path": "kabab",
"method": "camel",
"parameter": "camel",
"query": "kabab",
"header": "header",
"property": "camel",
"type": "camel"
}
}
]
}

If a casing rule is not specified for a particular element, then any casing will be allowed. There are no default values.

warning

Changing the casing for enum values, paths, query parameters, and properties is a breaking change for HTTP (aka RESTful) services because those values are passed directly in the HTTP request or response. Enum, method, and type names are never included in HTTP traffic.

note

Various Generators may emit code that is idiomatic to a particular language regardless of these casing rules; however, all generated code MUST send and receive values in the specified casing when communicating over service boundaries and/or respect the casing requirements of the protocol with which they do so.

JSON:API Error

Rule
@basketry/rules/lib/json-api-errorRequires that an "Error" type be defined that conforms to the JSON:API Error Object specification

Options

By default, violations of this rule will be displayed as errors. This may be overridden with the severity option.

By default, this requires strict conformity to the JSON:API Error Object spec. When in strict mode, status must be a string value if defined and code cannot be defined as an enum. When strict is explicitly set to false (true by default), then status can be a numeric type, and code can be a string enum type.

{
"rules": [
{
"rule": "@basketry/rules/lib/json-api-error",
"options": {
"severity": "warning",
"strict": false
}
}
]
}