Enforcing API and Data Model design rules with Specrtal
Jargon can automatically real-time validate your APIs and Data Models according to a set of custom defined rules, using the open-source Spectral rule language.
These rules can be used to check a variety of facets of your designs, such as:
- simplistic style rules, such as the casing of classes and properties
- the presence of required parameters
- data types for properties, such as on keys
Let’s take a look at how Jargon supports the creation of custom rulesets for enterprise installations and team accounts, and how all other users can select from Jargon’s curated list of rulesets to validate their own domains on.
If you’re unfamiliar with spectral, I suggest you take a look at their documentation, which takes you through everything you need to know.
The 30 second rundown, is that a spectral ruleset contains a collection of rules that each assert a specific thing about your model or API — such as the casing of classes, or the path string of APIs. When Jargon runs your spectral rules every failure will raise an error (or warning, or info) with enough information to help users figure out what is going wrong.
Jargon’s spectral rule editor
Jargon comes with an interactive rule editor, to help you design and test your spectral rules. It looks something like this:
Up the top-left is the spectral ruleset that you’re editing. It’s written in YAML, so indentation is important. Under the Ruleset is a button to run your ruleset and show the raw output in the output pane at the bottom of the screen.
In the top-right, is a sample JSON API spec to run your rules on. You can customise this to exhibit different failure conditions, and Jargon will save it alongside your ruleset — letting you progressively refine both your rules and test data.
Underneath the test data, is a text box for you to enter in a JSONPath expression (the language that Spectral uses to target specific chunks of the input document), and a button you can click to evaluate it. Here’s an example of what that looks like:
Here, I’ve entered the JSONPath expression “$.components.schemas.*~”.
The result of the evaluation is:
[
"petStore",
"Order",
"Payment"
]Which is the list of Class names in the API specification. The JSONPath evaluation button helps you target the correct parts of the API spec before you invest a lot of time in writing and debugging your rules.
Viewing spectral results
Jargon integrates spectral into its existing validation process.
For Domain modelling, spectral rules are aired as both annotations next to the line that caused the error, and within the error list:
For the API Editor, Jargon lists the spectral outputs alongside the other API validations:
Jargon specific fields for Domain modelling
Jargon adds some specific fields that can be checked against with spectral rules when using the Domain editor. These fields allow you to write specific data-modelling related rules that aren’t achievable by just testing the API specification.
Here’s an example of what Jargon generates as input to spectral when modelling a Domain:
{
"openapi": "3.0.0",
"info": {},
"paths": {},
"components": {
"schemas": {
"Payment": {
"type": "object",
"additionalProperties": false,
"properties": {
"status": {
"type": "string",
"enum": [
"Valid",
"Invalid"
],
"example": "Valid",
"description": ""
},
"order": {
"x-jargon-isKey": true,
"x-jargon-attr-jargon-reference": "true",
"type": "number",
"description": "This field is the identifier of Order (id). It's definition is:A unique identifier for an Order.This identifier is also used to make a Payment for this Order."
}
},
"description": "",
"x-jargon-ddd": "Entity"
}
}
}
}Jargon has inserted several x-attr extensions, specifically:
- x-jargon-isKey, which appears on all key properties of Entities
- x-jargon-ddd, which identifies what Domain-Driven-Deisgn type this class is (read what the different colours and class types mean)
- x-jargon-attr-*, is used to access any of the Jargon recognised key-value pairs. Eg: x-jargon-attr-jargon-reference identifies when a property is a reference (see our article on advanced modelling techniques to learn more)
Here’s a sample list of the recognised key-value pairs that you can test for (check the docs for the full list):
- x-jargon-attr-jargon-aggregation— When used on a property that is a Class, aggregate up all the type’s properties to the parent
- x-jargon-attr-jargon-required — Makes this property required. Also adds the ‘required=true’ to this property in an OpenAPI specification
- x-jargon-attr-jargon-reference— Treats a child property, which is a class (or an array of classes) as a reference pointer to that class, using the child’s class ID.
- x-jargon-attr-jargon-deprecated — Marks this property as deprecatd, flagging that it may be removed in the future.
- x-jargon-attr-jargon-abstract — If this is a super class, replaces the schema content with oneOf for each of the subClasses.
Who can use spectral rules in Jargon?
Everyone! But not everyone can create their own rules.
There are different levels of rules that Jargon can run, with the ruleset that is the most specific to a Domain taking precedence.
From least to most precedence:
3. Enterprise installation wide rulesets — these are only for enterprise customers and will apply to all Domains in the enterprise
2. Team / private user rulesets — these apply to all Domains within the team or private user account. You must be a member of a team, or have a private account to create these rulesets,
- Domain level — any Domain can choose to apply one of Jargon’s curated Spectral rulesets
Wrapping up:
So that’s how you can apply custom design rules to your APIs and Domain models.
If you have any further questions about Jargon’s use of spectral, you can:
- check the Getting Started Guide
- leave a comment below
- raise an issue at the jargon issue tracker GitHub repository
- Sign up for a free Jargon account and try some out for yourself.
