JSON Schema Rules
This page is dedicated to outlining the API governance rules for managing individual schema. The Spectral rules format, applicable to any JSON or YAML schema, is used here to identify patterns and anti-patterns relevant to governing JSON Schema artifacts.
These schema will also be validated in the context of any request or response associated with an API, but can also be managed centrally, reused across many APIs, then used to validate any schema in use as part of API operations and governance.
The JSON Schema Specification
JSON Schema is a declarative language for defining structure and constraints for JSON data. When it comes to data exchange, JSON Schema stands out as a powerful standard for defining the structure and rules of JSON data. It uses a set of keywords to define the properties of your data. While JSON Schema provides the language, validating a JSON instance against a schema requires a JSON Schema validator. The JSON validator checks if the JSON documents conform to the schema.
"$id": https://example.com/address.schema.json
"$schema": https://json-schema.org/draft/2020-12/schema
description: An address similar to http://microformats.org/wiki/h-card
type: object
properties:
postOfficeBox:
type: string
extendedAddress:
type: string
streetAddress:
type: string
locality:
type: string
region:
type: string
postalCode:
type: string
countryName:
type: string
required:
- locality
- region
- countryNameEssential JSON Schema Rules
These are the essential rules to begin with when it comes validating each API JSON Schema, ensuring that it meets a baseline of properties and metadata.
|
JSON Schema Draft 2020-12 ID - Each JSON Schema object MUST have a unique identifier, represented as a URL pointing to its location. The $id property in JSON Schema is used to establish the source of truth for any object being defined and validated.
|
|
|
JSON Schema Draft 2020-12 Properties - Schema has properties, providing more detail regarding the structure of each schema being applied as part of a request or a response
|
|
|
JSON Schema Draft 2020-12 ID Source URL - The $id property in any JSON Schema MUST contain a valid URL pointing to a central registry, repository, or another authoritative source for the object. This URL ensures that the object's source is always accessible and can be used for proper validation.
|
|
|
JSON Schema Draft 2020-12 Properties Names Camel Case - Schema property names are camel case, providing consistent casing across all the schema properties used by APIs
|
|
|
JSON Schema Draft 2020-12 Properties Descriptions - Schema properties should have descriptions that provide a narrative of the property contains, and how it can be used
|
|
|
JSON Schema Draft 2020-12 Schema - JSON Schema objects should always include the $schema property to explicitly indicate which version of the specification is being used. This property is essential for tooling and should consistently reference the latest version to ensure compatibility and up-to-date functionality.
|
|
|
JSON Schema Draft 2020-12 Schema Draft - The $schema property in a JSON Schema MUST always reference the latest draft of the specification to ensure consistent validation across all objects. Using the most up-to-date version of the specification helps maintain stability and reliability in the use of objects within any API.
|
|
|
JSON Schema Draft 2020-12 Properties String Minlength - Schema properties that are of the string type have the min length applied defining the shape of the property
|
|
|
JSON Schema Draft 2020-12 Title - JSON Schema objects MUST include a title property that describes the object in plain language while reflecting the object's file name. The title should convey the object's content and purpose, providing clarity on how it is intended to be used.
|
|
|
JSON Schema Draft 2020-12 Title Length info - The title of JSON Schema objects should be concise yet accurately describe the object's purpose. Keeping the title short ensures clarity and minimizes downstream impact on other items using the object.
|
|
|
JSON Schema Draft 2020-12 Title Pascal Case - The name of a JSON Schema object should always be in PascalCase to ensure readability and consistency across APIs. Using PascalCase helps maintain uniformity and aligns the object's name with its plain-language title.
|
|
|
JSON Schema Draft 2020-12 Description - Each JSON Schema object MUST include a description that explains, in plain language, the purpose and function of the object. This description should provide a clear overview of how the object is intended to be used within operations.
|
|
|
JSON Schema Draft 2020-12 Properties String Maxlength - Schema properties that are of the string type have the max length applied defining the shape of the property
|
|
|
JSON Schema Draft 2020-12 Description Length - The description for any JSON Schema object should be concise, ensuring it remains easy to read and understand for anyone using or interpreting it. This approach helps keep the schema self-contained while still providing enough context to inform its application wherever it is used.
|
|
|
JSON Schema Draft 2020-12 Type - JSON Schema objects should explicitly define their type, ensuring clarity about each object's structure. This allows tools utilizing the schema to accurately validate the object wherever it is applied.
|
|
|
JSON Schema Draft 2020-12 Properties Array Items - Schema properties that are of the type array must have an items property defined
|
|
|
JSON Schema Draft 2020-12 Required - All JSON Schema objects should explicitly define their properties and include at least one required property. Defining required properties enhances the accuracy and reliability of validation for each object.
|
|
|
JSON Schema Draft 2020-12 Properties Array Minitems - Schema properties that are of the type array should have a min items property defined
|
|
|
JSON Schema Draft 2020-12 Properties Array Maxitems - Schema properties that are of the type array should have a max items property defined
|
|
|
JSON Schema Draft 2020-12 Properties Enum - Schema property has enumerators, providing consistent values chosen by consumers when making requests
|