Skip to content
CMDB administrator tasks › Configure › API Insights › Configuration Management Database \(CMDB\) › Configuration Management › Extend ServiceNow AI Platform capabilities
Release: Australia · Updated: 2026-03-12 · Official documentation · View source

Validating API specifications in API Insights

You can access API specification validation rules to verify that your API specifications are complete, consistent, and adhere to best practices.

Validation rules identify structural issues early during import or analysis, improving overall API quality. You can manage these rules to enforce standardization across API specifications and reduce errors by checking for missing or incorrect fields before APIs are published or used in production.

Storing API specifications

The API Specification [sn_api_insights_ws_api_specification] table stores the specification documents that describe individual APIs. Each record includes the following details to identify the API to which the specification belongs and to manage multiple versions.

FieldDescription
NameName of the API.
VersionVersion of the API.
TypeFormat and version of the API specification standard being used. For example, `openapi3.0.0` for an OpenAPI specification.
StateCurrent status indicating whether the API specification has been validated against the applicable rules and the validation outcome. Valid values are:- Unprocessed: Indicates that the API specification hasn’t been validated. - Valid: Indicates that the API specification was validated and processed successfully or with warnings. If warnings are present, details are displayed in the Message field. - Invalid: Indicates that the API specification was validated but contains errors. Error details are displayed in the Message field.
SpecificationFull content of the API specification file. Note: For OpenAPI, includes the complete OpenAPI document describing endpoints, methods, and schema.
MessageMessages are generated after processing all validation rules for the specification type. They include errors or warnings with explanations.

Validation rule structure

The Specification Validation Rule [sn_api_insights_ws_spec_validation_rule] table stores validation rules for the API specifications defined in the API Specification [sn_api_insights_ws_api_specification] table.

Note: The sn_cmdb_editor role is required to edit or delete validation rules, and the cmdb_read role to view them.

Each validation rule contains the following key components:

ComponentDescription
SpecificationAPI specification for which the rule is designed.
VersionVersion of the API specification the rule validates. If specified, the rule applies only to those versions. To restrict validation to specific versions, specify them in the Version field. Separate multiple values with commas. For example, 1.0,1.1,2.0.Note: If the Version field is left empty, the rule runs for all installed versions of the specified API specification type.
TypeType of validation to perform. The valid values are:- Path: Verifies that the specific keys are present within arrays of objects, individual objects, or both, in the designated sections of the API specification document. - Expected value: Validates whether the specified key matches the expected values specified in the Value field. This validation applies only to a single key specified in the Key field.
KeyPart of the specification to verify. If no expected value is provided, you can enter multiple keys in the Key field, separated by commas.
ValueExpected values for the key specified in the Key field. Separate multiple values with commas.
SeveritySeverity level of the validation rule outcome, either a warning or an error.Note: When set to warning, the API specification remains valid if the rule isn’t met, indicating it is not a failure, and only a message is displayed.
MessageExplanation of the issue when the rule is triggered.
ActiveOption to activate the rule. Only active rules are triggered by the API Specification Validation scheduled job.

API specification validation process

The API Specification Validation scheduled job automatically validates unprocessed API specifications against active rules based on their specification type to ensure compliance with required standards.

The validation process includes:

  1. Retrieving all active validation rules from the Specification Validation Rule [sn_api_insights_ws_spec_validation_rule] table.
  2. Selecting APIs marked as unprocessed in the API Specification [sn_api_insights_ws_api_specification] table.
  3. Applying relevant validation rules to each selected API based on its specification type, such as OpenAPI.
  4. Verifying the presence or correctness of specific fields or their values within the API specification.
  5. Updating the processing status and capturing any errors or warnings.

Predefined rules for OpenAPI specifications

By default, the application includes the following validation rules for OpenAPI specifications:

  • Validate tags

    Verifies that each tag in the API specification includes a name field. If the name field is missing, the system returns a warning message but marks the specification as valid.

  • Validate required sections

    Verifies that the API specification includes the required top-level sections: info, paths, and components. If any of these sections are missing, the system returns an error message and marks the specification as invalid.

  • Validate servers section

    Verifies whether the API specification includes a servers section that defines the server endpoints. If the servers section is missing, the system returns an error message and marks the specification as invalid.

These predefined rules verify critical sections such as tagging, metadata, and server definitions in OpenAPI specifications.