Basketry 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.

Descriptions

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

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

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

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

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

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

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.

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" }
    }
  ]
}

Pluralization

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" }
    }
  ]
}

Casing

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. Query parameters are not technically case-sensitive. Enum, method, and type names are never included in HTTP traffic.

Also note that 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

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
      }
    }
  ]
}

Generated with generator-ts-console