Validating API specifications in API Insights

  • Release version: Zurich
  • Updated July 31, 2025
  • 3 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Validating API specifications in API Insights

    ServiceNow’s API Insights provides API specification validation rules to help you ensure your API specifications are complete, consistent, and follow best practices. These validation rules detect structural issues early in the import or analysis process, improving API quality and reducing errors before APIs are published or used in production.

    Show full answer Show less

    Managing API Specifications

    API specifications are stored in the API Specification [snapiinsightswsapispecification] table, which holds details such as the API name, version, specification format (e.g., OpenAPI 3.0.0), validation state, full specification content, and validation messages. The validation state indicates whether the specification is unprocessed, valid (with or without warnings), or invalid (with errors), helping you track compliance status centrally.

    Validation Rules

    Validation rules are configured in the Specification Validation Rule [snapiinsightswsspecvalidationrule] table and define the criteria against which API specifications are checked. Key components of each rule include:

    • Specification: The API specification type the rule applies to.
    • Version: Specific API spec versions the rule targets (optional).
    • Type: Validation type, such as verifying presence of keys (Path) or matching expected values.
    • Key and Value: The exact fields and expected values to validate.
    • Severity: Whether the rule triggers a warning or error.
    • Message: Description provided when the rule is triggered.
    • Active: Controls whether the rule is enforced during validation.

    Note that editing or deleting validation rules requires the sncmdbeditor role, and viewing them requires the cmdbread role.

    Validation Process

    The API Specification Validation scheduled job automates validation by:

    • Retrieving all active validation rules.
    • Selecting unprocessed API specifications.
    • Applying relevant rules based on specification type.
    • Checking for required fields, correct values, and structural integrity.
    • Updating the specification’s validation state and recording messages.

    This process enforces standardization and helps prevent publishing APIs with incomplete or incorrect specifications.

    Predefined Validation Rules for OpenAPI

    The application includes built-in validation rules for OpenAPI specifications to verify critical sections:

    • Validate tags: Ensures each tag has a name field; missing names generate warnings but do not invalidate the spec.
    • Validate required sections: Checks for mandatory top-level sections info, paths, and components; missing sections trigger errors and mark the specification as invalid.
    • Validate servers section: Confirms presence of the servers section defining server endpoints; absence causes errors and invalidation.

    These rules help maintain essential metadata and structural correctness for OpenAPI documents.

    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.
    Table 1. API specification details
    Field Description
    Name Name of the API.
    Version Version of the API.
    Type Format and version of the API specification standard being used. For example, openapi3.0.0 for an OpenAPI specification.
    State Current 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.
    Specification Full content of the API specification file.
    Note:
    For OpenAPI, includes the complete OpenAPI document describing endpoints, methods, and schema.
    Message Messages 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:

    Table 2. Validation rule components
    Component Description
    Specification API specification for which the rule is designed.
    Version Version 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.
    Type Type 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.
    Key Part of the specification to verify. If no expected value is provided, you can enter multiple keys in the Key field, separated by commas.
    Value Expected values for the key specified in the Key field. Separate multiple values with commas.
    Severity Severity 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.
    Message Explanation of the issue when the rule is triggered.
    Active Option 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.