All Spectral rules used in the IPA validation are defined in rulesets grouped by IPA number (IPA-XXX.yaml). These rulesets are imported into the main IPA ruleset ipa-spectral.yaml which is used for running the validation.
Below is a list of all available rules, their descriptions and severity levels.
Rules are based on http://go/ipa/IPA-5.
Rule checks for the following conditions:
- Exception rule names must start with 'xgen-IPA-' prefix
- Each exception must include a non-empty reason as a string
- This rule itself does not allow exceptions
Rules are based on http://go/ipa/IPA-102.
Rule checks for the following conditions:
- All path segments that are not path parameters
- Only the resource identifier part before any colon in custom method paths (e.g.,
resourcein/resource:customMethod) - Path parameters should also follow camelCase naming
- Certain values can be exempted via the ignoredValues configuration that can be supplied as
ignoredValuesargument to the rule - Paths with
x-xgen-IPA-exceptionfor this rule are excluded from validation - Double slashes (//) are not allowed in paths
Rule checks for the following conditions:
- Paths must follow a pattern where resource names and path parameters strictly alternate
- Even-indexed path segments should be resource names (not path parameters)
- Odd-indexed path segments should be path parameters
- Paths with
x-xgen-IPA-exceptionfor this rule are excluded from validation
Rule checks for the following conditions:
- All path segments that are not path parameters must match pattern
/^[a-z][a-zA-Z0-9]*$/ - Path parameters (inside curly braces) are excluded from validation
- Custom methods (segments containing colons) are excluded from validation
- Paths with
x-xgen-IPA-exceptionfor this rule are excluded from validation - Each non-parameter path segment must start with a lowercase letter followed by any combination of ASCII letters and numbers
Rules are based on http://go/ipa/IPA-104.
Rule checks for the following conditions:
- Only applies to resource collection identifiers
- For singleton resources, verifies the resource has a GET method
- For regular resources, verifies there is a single resource path with a GET method
Rule checks for the following conditions:
- Applies only to 2xx responses of GET methods on single resources or singleton resources
- Verifies the response is not an array or paginated result
- Different error messages are provided for standard vs singleton resources
Rule checks for the following conditions:
- Applies only to GET methods on single resources or singleton resources
- Verifies the 200 OK response code is present
- Fails if the method lacks a 200 OK response or defines a different 2xx status code
Rule checks for the following conditions:
- Applies only to 2xx responses of GET methods on single resources or singleton resources
- Verifies the schema references a predefined schema (not inline)
- Confirms the referenced schema name ends with "Response" suffix
Rule checks for the following conditions:
- Applies only to 2xx responses of GET methods on single resources or singleton resources
- Searches through the schema to find any properties marked with writeOnly attribute
- Fails if any writeOnly properties are found in the response schema
Rule checks for the following conditions:
- Applies only to GET methods on single resources or singleton resources
- Verifies that the operation object does not contain a requestBody property
Rules are based on http://go/ipa/IPA-105.
Rule checks for the following conditions:
- Applies only to GET methods on resource collection paths
- Ignores singleton resources
- Verifies the 200 OK response code is present
- Fails if the method lacks a 200 OK response or defines a different 2xx status code
Rule checks for the following conditions:
- Applies only to GET methods on resource collection paths
- Ignores singleton resources
- Verifies that the operation object does not contain a requestBody property
Rule checks for the following conditions:
- Applies only to resource collection paths
- Ignores singleton resources
- Verifies the resource path has a GET method
- Fails if the resource path does not have a GET method
- Applies only to resource collection paths with JSON content types
- Ignores singleton resources
- Ignores responses without a schema or non-paginated responses
- A response is considered paginated if it has a schema with a 'results' array property
- Verifies that the schema of items in the 'results' array matches the schema used in the Get method response
- Fails if the Get method doesn't have a schema reference or if the schemas don't match
- Validation ignores resources without a Get method
- Paths with
x-xgen-IPA-exceptionfor this rule are excluded from validation
Rules are based on http://go/ipa/IPA-106.
Rule checks for the following conditions:
- Applies only to POST methods on resource collection paths (non-singleton resources)
- Applies only to JSON content types
- Verifies the schema references a predefined schema (not inline)
- Confirms the referenced schema name ends with "Request" suffix
Rule checks for the following conditions:
- Applies only to POST methods on resource collection paths (non-singleton resources)
- Verifies the operation does not contain query parameters
- Ignores specified parameters like 'pretty' and 'envelope' via configuration
Validation checks the POST method for resource collection paths.
- Validation ignores resources without a Get method.
readOnly:trueproperties of Get method response will be ignored.writeOnly:trueproperties of Create method request will be ignored.- Property comparison is based on
typeandnamematching. oneOfanddiscriminatordefinitions must match exactly.
Rule checks for the following conditions:
- Applies only to POST methods on resource collection paths (non-singleton resources)
- Applies only to JSON content types
- Searches through the request schema to find any properties marked with readOnly attribute
- Fails if any readOnly properties are found in the request schema
Rule checks for the following conditions:
- Applies only to POST methods on resource collection paths (non-singleton resources)
- Verifies the 201 Created response code is present
- Fails if the method lacks a 201 Created response or defines a different 2xx status code
Rule checks for the following conditions:
- Applies only to POST methods on resource collection paths
- Applies only to JSON response content types
- Verifies that both Create and Get methods have schema references
- Confirms that the Create method 201 response schema reference matches the Get method response schema reference
- Ignores resources without a Get method
- Paths with
x-xgen-IPA-exceptionfor this rule are excluded from validation
Rules are based on http://go/ipa/IPA-107.
Validation checks the PATCH/PUT methods for single resource paths and singleton resources.
- Query parameters
envelopeandprettyare exempt from this rule - Operation objects with
x-xgen-IPA-exceptionfor this rule are excluded from validation
Validation checks the PATCH/PUT methods for single resource paths and singleton resources.
- Operation objects with
x-xgen-IPA-exceptionfor this rule are excluded from validation
- Applies only to single resource paths and singleton resources with JSON content types
- Ignores singleton resources and responses without a schema
- Validation ignores resources without a Get method
- Fails if the Get method doesn't have a schema reference or if the schemas don't match
- Paths with
x-xgen-IPA-exceptionfor this rule are excluded from validation
Rule checks for the following conditions:
- Applies only to Update methods on single resource paths or singleton resources
- Applies only to JSON content types
- Searches through the request schema to find any properties marked with readOnly attribute
- Fails if any readOnly properties are found in the request schema
Validation checks the PATCH/PUT methods for single resource paths and singleton resources.
- Validation ignores resources without a Get method.
readOnly:trueproperties of Get method response will be ignored.writeOnly:trueproperties of Update method request will be ignored.- Property comparison is based on
typeandnamematching. oneOfanddiscriminatordefinitions must match exactly.
UpdateRequest suffixed object.
Rule checks for the following conditions:
- Applies to PUT/PATCH methods on single resource paths and singleton resources
- Applies only to JSON content types
- Validation only applies to schema references to a predefined schema (not inline)
- Confirms the referenced schema name ends with "Request" suffix
Rules are based on http://go/ipa/IPA-108.
Rule checks for the following conditions:
- Applies to 204 responses in DELETE methods for single resource endpoints (with path parameters)
- Verifies that the response does not contain a schema property
- Fails if any content type in the response has a defined schema as reference
- Skips validation for collection endpoints (without path parameters)
Rule checks for the following conditions:
- Applies to all DELETE methods for single resource endpoints (with path parameters)
- Verifies the 204 No Content response code is present
- Fails if the method lacks a 204 No Content response or defines a different 2xx status code
- Ensures no other 2xx response codes are defined
- Fails if the 204 status code is missing or if other 2xx responses exist
- Skips validation for collection endpoints (without path parameters)
Rule checks for the following conditions:
- Applies to all DELETE methods for single resource endpoints (with path parameters)
- Verifies that the operation object does not contain a requestBody property
- Fails if any requestBody is defined for the DELETE method
- Skips validation for collection endpoints (without path parameters)
Rules are based on http://go/ipa/IPA-109.
Rule checks for the following conditions:
- Applies only to paths containing custom method identifiers (with colon format)
- Verifies the HTTP methods used are either GET or POST
- Fails if any other HTTP methods are used (PUT, DELETE, PATCH, etc.)
- Fails if multiple valid methods are defined for the same custom method endpoint
Rule checks for the following conditions:
- Applies only to paths containing custom method identifiers (with colon format)
- Extracts the method name portion following the colon
- Verifies the method name is not empty or blank
- Validates that the method name uses proper camelCase formatting
- Fails if the method name contains invalid casing (such as snake_case, PascalCase, etc.)
Rule checks for the following conditions:
- Identifies paths containing a colon (potential custom methods)
- Validates that the path follows proper custom method format
- Does not validate after the colon (xgen-IPA-109-custom-method-must-use-camel-case rule validates the method name)
- Fails if a slash appears before a colon
- Fails if multiple colons appear in the path
- Fails if other than an alphabetical character or a closing curly brace appears before a colon
Rules are based on http://go/ipa/IPA-110.
Rule checks for the following conditions:
- Only applies to List methods (GET operations that return collections of resources)
- Checks if List method has a response schema defined
- Checks that the 200 response schema references a schema with a "Paginated" prefix
Rule checks for the following conditions:
- Only applies to List methods (GET operations that return collections of resources)
- Verifies the 200 response schema has the required results fields
Rule checks for the following conditions:
- Only applies to List methods (GET on resource collection paths)
- Verifies the operation includes itemsPerPage query parameter
- Verifies the itemsPerPage query parameter is not required
- Verifies the itemsPerPage query parameter has a default value of 100
Rule checks for the following conditions:
- Only applies to List methods (GET on resource collection paths)
- Verifies the operation includes pageNum query parameter
- Verifies the pageNum query parameter is not required
- Verifies the pageNum query parameter has a default value of 1
Rule checks for the following conditions:
- Only applies to List methods (GET on resource collection paths)
- Checks if includeCount query parameter exists
- If it exists, verifies the includeCount parameter is not required
Rule checks for the following conditions:
- Only applies to List methods (GET operations that return collections of resources)
- Verifies the response schema includes a links field of type array
Rules are based on http://go/ipa/IPA-112.
Rule checks for the following conditions:
- Searches through all schemas in the API definition
- Identifies property names that match "project" (case-insensitive)
- Ignores fields where prohibited words appear with specified words (e.g., "gcpProjectId")
- Reports any instances where these field names are used
- Suggests using "group", "groups", or "groupId" as alternatives
Rule checks for the following conditions:
- Searches through all schemas in the API definition
- Identifies property names that are not in camelCase format
- Reports any instances where these field names are not in camelCase format
Rule checks for the following conditions:
- Applies only to properties with type 'boolean'
- Identifies property names that start with "is" followed by an uppercase letter
- Suggests using the direct adjective form instead (e.g., "disabled" instead of "isDisabled")
Rules are based on http://go/ipa/IPA-113.
Rule checks for the following conditions:
- Applies only to singleton resources that are identified as resource collection identifiers
- Checks that the resource has a GET method defined
- Examines all 2xx response schemas from the GET method
- Verifies that no schema contains 'id' or '_id' properties in their object definitions
- Fails if any response schema contains these identifier properties
Rule checks for the following conditions:
- Applies only to singleton resources
- Checks that the resource does not have a DELETE method defined
Rule checks for the following conditions:
- Applies only to singleton resources
- Checks that the resource has the PUT and/or PATCH methods defined
Rules are based on http://go/ipa/IPA-114.
This rule checks that all 4xx and 5xx error responses reference the ApiError schema.
Rule checks that:
- ApiError schema has badRequestDetail field
- badRequestDetail must include an array of fields
- Each field must include description and field properties
- This rule does not allow exceptions
This rule checks that all authenticated endpoints (those without explicit 'security: []' and not containing '/unauth' in the path) include 401 and 403 responses.
This rule checks that all endpoints with path parameters (identified by '{param}' in the path) include a 404 response to handle the case when the requested resource is not found.
Rules are based on http://go/ipa/IPA-117.
Rule checks for description property in the following components:
- Info object
- Tags
- Operation objects
- Inline schema properties for operation object requests and responses
- Parameter objects (in operations and components)
- Schema properties The rule also fails if the description is an empty string.
Rule checks the format of the description property in the following components:
- Info object
- Tags
- Operation objects
- Inline schema properties for operation object requests and responses
- Parameter objects (in operations and components)
- Schema properties
Rule checks the format of the description property in the following components:
- Info object
- Tags
- Operation objects
- Inline schema properties for operation object requests and responses
- Parameter objects (in operations and components)
- Schema properties
The rule ignores descriptions that end with
|, i.e. inline markdown tables
Rule checks the format of the descriptions for components:
- Info object
- Tags
- Operation objects
- Inline schema properties for operation object requests and responses
- Parameter objects (in operations and components)
- Schema properties The rule validates that the description content does not include opening and/or closing HTML tags.
Rule checks the format of the descriptions for components:
- Info object
- Tags
- Operation objects
- Inline schema properties for operation object requests and responses
- Parameter objects (in operations and components)
- Schema properties The rule validates that the description content does not include inline markdown tables.
Rule checks the format of the descriptions for components:
- Tags
- Operation objects
- Inline schema properties for operation object requests and responses
- Parameter objects (in operations and components)
- Schema properties
The rule validates that the description content does not include inline markdown links. The rule ignores HTML
<a>links - this is covered byxgen-IPA-117-description-must-not-use-html.
- The rule only applies to 2xx responses
- The rule ignores JSON and YAML responses (passed as
allowedTypes) - The rule ignores responses with
format: 'binary'(i.e. file types) - The rule checks for the presence of the example property as a sibling to the
schemaproperty, or inside theschemaobject
schemaexamplesexampleoneOf,anyOforallOfpropertiesadditionalProperties
The rule applies to the following components:
- Inline operation responses/request bodies (JSON only)
- Inline operation response/request body properties (JSON only)
- Inline operation response/request body array items (JSON only)
- Schemas defined in
components/schemas - Schema properties defined in
components/schemas itemsproperties defined incomponents/schemasThe rule is applied to the unresolved OAS, and ignores components with$refproperties. Specific paths can be ignored using theignoredPathsoption.
The rule checks for the presence of the schema, examples or example property in:
- Operation parameters
- Parameters defined in
components/parameters
Rules are based on http://go/ipa/IPA-118.
additionalProperties: false
This rule checks that schemas don't restrict additional properties by setting additionalProperties: false.
Schemas without explicit additionalProperties settings (which default to true) or with additionalProperties set to true are compliant.
This rule checks all nested schemas, but only parent schemas can be marked for exception.
Rules are based on http://go/ipa/IPA-119.
Rules are based on http://go/ipa/IPA-121.
Rules are based on http://go/ipa/IPA-123.
Rule checks for the following conditions:
- Applies to all enum value arrays defined in the OpenAPI schema
- Resolves the schema object that contains the enum values
- Validates each enum value individually against the UPPER_SNAKE_CASE pattern
- Skips validation if the schema has an exception defined for this rule
Rule checks for the following conditions:
- Applies to inline enum values
- Validates that each enum array has 20 or fewer values
- Reusable enum schemas will be ignored
- Skips validation if the schema has an exception defined for this rule
- This validation threshold can be adjusted by changing the functionOptions.maxEnumValues parameter
Rules are based on http://go/ipa/IPA-124.
Rule checks for the following conditions:
- All schema objects with type 'array' must have a maxItems property
- The maxItems value must be set below the threshold of 100
- maxItems: Required integer parameter specifying the maximum allowed array size (default: 100)
- ignore: Required array parameter listing property names to be exempted from validation
Rules are based on http://go/ipa/IPA-125.
Rule checks for the following conditions:
- Applies only to schemas with
oneOfcontaining references - Ensures a
discriminatorproperty is present with a validpropertyName - Validates that
discriminator.mappingcontains exactly the same number of entries asoneOfreferences - Validates that each
discriminator.mappingvalue matches a reference in theoneOfarray - Ignores
oneOfdefinitions with inline schemas
- The
discriminator.mappingmust have the same number of entries as there are references in theoneOfarray - Each value in the
discriminator.mappingmust match one of the$refvalues in theoneOfarray - Each
$refin theoneOfarray must have a corresponding entry in thediscriminator.mapping - Example:
This is valid because there are exactly 2 mappings for 2 oneOf references, and all values match.
oneOf: - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Cat' discriminator: propertyName: type mapping: dog: '#/components/schemas/Dog' cat: '#/components/schemas/Cat'
Rule checks for the following conditions:
- Applies to schemas with
oneOfarrays - Ensures no mixing of base types with references
- Ensures no multiple different base types in the same oneOf
- Base types considered are: integer, string, boolean, number
- Using the same base type multiple times is allowed (e.g., multiple string enums)
Using oneOf with multiple primitive types can lead to ambiguity and validation problems. Clients may not be able to properly determine which type to use in which context. Instead, use more specific object types with clear discriminators.
Rules are based on http://go/ipa/IPA-126.
Rule checks for the following conditions:
- All tag names defined in the OpenAPI tags object should use Title Case
- Title Case means each word starts with an uppercase letter, and the rest are lowercase
- Certain abbreviations (like "API", "AWS", etc.) in the ignoreList are allowed to maintain their casing
- Grammatical words (like "and", "or", "the", etc.) are allowed to be all lowercase
This rule includes two configuration options:
ignoreList: Words that are allowed to maintain their specific casing (e.g., "API", "AWS", "DNS")grammaticalWords: Common words that can remain lowercase in titles (e.g., "and", "or", "the")