Spectral continues to evolve to meet the governance needs of API teams looking to enforce quality through customizable linting rules. I’m happy to introduce a new core function—or—which adds more power to your rulesets and API style guides.
What are Spectral Core Functions?
Spectral core functions are the building blocks of rules in Spectral. They encapsulate reusable logic like checking for the existence of a property, evaluating a pattern, or comparing values. You pair a core function with a given JSONPath expression and some functionOptions to write powerful, declarative rules for your OpenAPI, Arazzo, or AsyncAPI documents.
The current list of core functions is as follows:
| Function | Description |
alphabetical | Enforce alphabetical content, for simple arrays, or for objects by passing a key. |
enumeration | Checks if the field value exist in this set of possible values. |
falsy | The value should be false, ””, 0, null or undefined. |
length | Count the length of a string or an array, the number of properties in an object, or a numeric value, and define minimum and/or maximum values. |
pattern | Use regular expressions to match or notMatch. |
casing | Text must match a certain case, like camelCase or snake_case. |
schema | Use JSON Schema (draft 4, 6, 7, 2019-09, or 2020-12) to treat the contents of the $given JSON Path as a JSON instance. |
truthy | The value should not be false, ””, 0, null or undefined. |
defined | The value must be defined, meaning it must be anything but undefined. |
undefined | The value must be undefined. |
unreferencedReusableObject | This function identifies unreferenced objects within a document. |
or **NEW** | Communicate that one or more of these properties is required to be defined. |
xor | Communicate that one of these properties is required, and no more than one is allowed to be defined. |
typedEnum | When both a type and enum are defined for a property, the enum values must respect the type. |
Why is an `or` Function Useful?
The new or function lets you assert that at least one of several specified properties must exist. This is particularly useful when a schema or object can be validated in several ways, and you want to cater for that flexibility across teams or APIs. This can be useful in upholding a strong basis for quality API documentation but remaining practical with respect to the needs of decentralized decision making and use-case nuances.
Function Signature
function: or
functionOptions:
properties:
propertyName1
propertyName2
propertyName3
Example 1: Descriptiveness Text Must Exist on Schemas
Imagine enforcing documentation/design practices across API schemas. You might require that each schema is documented in some form to express its use (or purpose) for consumers and other API designers – but not necessarily force the same mechanism in expressiveness onto all schema authors. As one might use a title, another a summary, and another a longer description. The or function allows you to express that flexibility.
rules:
schemas-descriptive-text-exists:
description: Defined schemas must have one or more of `title`, `summary`, and/or `description`.
given: "$.components.schemas.*"
then:
function: or
functionOptions:
properties:
- title
- summary
- description
The above ruleset ensures that all schemas are at least somewhat documented to express their purpose, without forcing a specific documentation style.
Example 2: Ensuring Helpful Hints for String Schemas
In another common case, you may want to ensure that every type: string schema includes a helpful hint or constraint for developers – via a format, an example, or a pattern. Here again, more than one is acceptable, but at least one should exist:
rules:
string-schemas-must-have-hint:
description: String schemas must include a format, example, or pattern to aid consumers.
given: "$.components.schemas.*[?(@.type=='string')]"
then:
function: or
functionOptions:
properties:
- format
- example
- pattern
Community Contribution
Big shout-out to Clyde Cutting 💛 for adding this capability. He had the need for this functionality as part of the great work happening within the Financial Data Exchange and their FDX API Style Guide for Open Banking APIs. Community contributions like these help Spectral grow into an even more powerful and practical tool.
Try It Out
Update to the latest version of Spectral and give the or function a spin in your own rulesets. Whether you’re enforcing schema documentation, naming conventions, or structural flexibility, or gives you additional declarative means to express it.
