or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

bundling.md dereferencing.md index.md parsing.md resolution.md validation.md

tile.json

API Validation

Comprehensive validation system that parses, dereferences, and validates OpenAPI/Swagger specifications. Performs two levels of validation: JSON schema validation against official OpenAPI/Swagger schemas, and specification rule validation for semantic correctness.

Capabilities

Validate Function

Performs complete validation of OpenAPI/Swagger specifications including parsing, dereferencing, and validation.

/**
 * Parses, dereferences, and validates the given OpenAPI/Swagger API
 * @param path - File path or URL of the OpenAPI definition (optional if api provided)
 * @param api - OpenAPI definition object to validate instead of reading from path
 * @param options - Validation options (optional)
 * @param callback - Error-first callback (optional, returns Promise if omitted)
 * @returns Promise resolving to the validated and dereferenced OpenAPI definition
 */
function validate(
  path?: string,
  api?: OpenAPI.Document,
  options?: SwaggerParser.Options,
  callback?: SwaggerParser.ApiCallback
): Promise<OpenAPI.Document>;

Named Validate Export

Shorthand validation function available as named export.

/**
 * Named export for validation without creating SwaggerParser instance
 * @param path - File path or URL of the OpenAPI definition
 * @param options - Validation options
 * @param callback - Error-first callback
 * @returns Promise resolving to the validated OpenAPI definition
 */
export function validate(
  path?: string,
  api?: OpenAPI.Document,
  options?: SwaggerParser.Options,
  callback?: SwaggerParser.ApiCallback
): Promise<OpenAPI.Document>;

Instance Validate Method

Validate method available on SwaggerParser instances.

/**
 * Instance method for validating OpenAPI/Swagger specifications
 * @param path - File path or URL of the OpenAPI definition
 * @param api - OpenAPI definition object to validate instead of reading from path
 * @param options - Validation options
 * @param callback - Error-first callback
 * @returns Promise resolving to the validated OpenAPI definition
 */
public validate(
  path?: string,
  api?: OpenAPI.Document,
  options?: SwaggerParser.Options,
  callback?: SwaggerParser.ApiCallback
): Promise<OpenAPI.Document>;

Usage Examples:

import SwaggerParser, { validate } from "@apidevtools/swagger-parser";

// Basic validation
try {
  const api = await SwaggerParser.validate("./petstore.yaml");
  console.log("API is valid:", api.info.title);
} catch (err) {
  console.error("Validation failed:", err.message);
}

// Using named export
const api = await validate("./api.yaml");

// Validation with custom options
const api = await SwaggerParser.validate("./api.yaml", {
  validate: {
    schema: true,  // Enable JSON schema validation
    spec: false    // Disable spec rule validation
  }
});

// Validate an API object directly
const apiObject = {
  openapi: "3.0.0",
  info: { title: "My API", version: "1.0.0" },
  paths: {}
};
const validatedApi = await SwaggerParser.validate(apiObject);

// Using callback style
SwaggerParser.validate("./api.yaml", (err, api) => {
  if (err) {
    console.error("Validation failed:", err);
  } else {
    console.log("Valid API:", api.info.title);
  }
});

Validation Options

interface Options {
  validate?: {
    /** Enable/disable JSON schema validation against OpenAPI/Swagger schemas */
    schema?: boolean;
    /** Enable/disable specification rule validation (Swagger 2.0 only) */
    spec?: boolean;
  };
}

Validation Levels

Schema Validation

Validates against official JSON schemas:

Swagger 2.0: Swagger 2.0 Schema
OpenAPI 3.0: OpenAPI 3.0 Schema
OpenAPI 3.1: OpenAPI 3.1 Schema

Specification Validation (Swagger 2.0 only)

Additional validation rules for Swagger 2.0 specifications:

Unique operation IDs across all paths
Required path parameters must exist in path string
Path parameters must be marked as required
No duplicate parameters within operations
Body and formData parameters are mutually exclusive
File parameters require appropriate MIME types
Valid HTTP response codes
Required properties must exist in schema definitions

Circular Reference Handling

// Validation handles circular references automatically
const api = await SwaggerParser.validate("./api-with-circles.yaml", {
  dereference: {
    circular: true  // Allow circular references
  }
});

Error Handling

Validation throws errors for various failure scenarios:

try {
  const api = await SwaggerParser.validate("./api.yaml");
} catch (error) {
  // Schema validation errors
  if (error.message.includes("schema validation failed")) {
    console.error("Schema validation failed:", error.details);
  }
  
  // Spec validation errors (Swagger 2.0)
  if (error.message.includes("Validation failed")) {
    console.error("Spec validation failed:", error.message);
  }
  
  // Circular reference errors
  if (error instanceof ReferenceError && error.message.includes("circular")) {
    console.error("Circular references not allowed");
  }
}

Common Validation Errors:

Invalid OpenAPI/Swagger version format
Missing required properties (info, paths, etc.)
Invalid schema types or structures
Duplicate operation IDs (Swagger 2.0)
Path parameter mismatches (Swagger 2.0)
Invalid HTTP response codes (Swagger 2.0)
Circular reference violations