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
- yarn
- pnpm
npm install @basketry/rules
yarn add @basketry/rules
pnpm add @basketry/rules
Basic Usage
{
"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-description | Requires all methods to have a description |
@basketry/rules/lib/parameter-description | Requires all method parameters to have a description |
@basketry/rules/lib/property-description | Requires all type properties to have a description |
@basketry/rules/lib/type-description | Requires all types to have a description |
@basketry/rules/lib/description | Combines 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-length | Requires 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-status | Requires that HTTP DELETE status codes must be 200 , 202 , or 204 |
@basketry/rules/lib/http-get-status | Requires that HTTP GET status codes must be 200 , 204 , or 206 |
@basketry/rules/lib/http-patch-status | Requires that HTTP PATCH status codes must be 200 , 202 , or 204 |
@basketry/rules/lib/http-post-status | Requires that HTTP POST status codes must be 200 , 201 , 202 , or 204 |
@basketry/rules/lib/http-put-status | Requires that HTTP PUT status codes must be 200 , 201 , 202 , or 204 |
@basketry/rules/lib/http-no-content-status | Requires 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-status | Combines 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-pagination | Requires methods that return arrays define offest and limit paremters |
@basketry/rules/lib/relay-pagination | Requires 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-id | Requires 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-envelope | Requires 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-body | Requires that request bodies (if defined) be objects or unions of objects. |
@basketry/rules/lib/object-response-body | Requires that response bodies (if defined) be objects or unions of objects. |
@basketry/rules/lib/object-body | Combines 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-body | Prohibits HTTP DELETE methods from defining a request body. |
@basketry/rules/lib/no-http-get-body | Prohibits HTTP GET methods from defining a request body. |
@basketry/rules/lib/no-http-head-body | Prohibits HTTP HEAD methods from defining a request body. |
@basketry/rules/lib/no-http-options-body | Prohibits HTTP OPTIONS methods from defining a request body. |
@basketry/rules/lib/no-http-trace-body | Prohibits HTTP TRACE methods from defining a request body. |
@basketry/rules/lib/no-disallowed-http-body | Combines 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-properties | Requires 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-pluralization | Requires that enums have singular names. |
@basketry/rules/lib/parameter-pluralization | Requires that array parameters have pluralized names and non-array parameters have singular names. |
@basketry/rules/lib/property-pluralization | Requires that array properties have pluralized names and non-array properties have singular names. |
@basketry/rules/lib/pluralization | Combines 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/casing | Defines casing requirements for the various parts of a service |
Options
Casing values must be one of the following:
snake
- eg. some_item_namepascal
- eg. SomeItemNamecamel
- eg. someItemNamekebab
- eg. some-item-nameheader
- eg. Some-Item-Nameconstant
- 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.
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.
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-error | Requires 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
}
}
]
}