Skip to main content

OpenAPI Validation

Vague can validate generated data against OpenAPI specifications, ensuring your test data conforms to your API contracts.

Basic Validation​

Use the -v flag to validate against an OpenAPI spec:

vague data.vague -v openapi.json

Schema Mapping​

Map collection names to schema names with -m:

vague data.vague -v openapi.json -m '{"invoices": "Invoice", "customers": "Customer"}'

The mapping tells Vague which OpenAPI schema to validate each collection against.

Auto-Detection​

If collection names match schema names (case-insensitive), mapping is automatic:

dataset Data {
  invoices: 100 of Invoice,  // Validates against Invoice schema
  customers: 50 of Customer   // Validates against Customer schema
}
vague data.vague -v openapi.json
# Automatically maps invoices -> Invoice, customers -> Customer

Validate-Only Mode​

Skip data output and only run validation (useful for CI):

vague data.vague -v openapi.json --validate-only

Returns exit code 0 on success, 1 on validation failure.

Validation Output​

Successful validation:

✓ invoices: 100 records validated against Invoice
✓ customers: 50 records validated against Customer

Failed validation:

✗ invoices[23]: amount must be >= 0
✗ invoices[45]: status must be one of: draft, sent, paid
✗ customers[12]: email must match format "email"

Validation failed: 3 errors

Practical Examples​

CI Pipeline​

# Generate and validate, fail if invalid
vague fixtures.vague -v api.json --validate-only

# Or with explicit mapping
vague fixtures.vague -v api.json -m '{"orders": "Order"}' --validate-only

Development Workflow​

# Generate, validate, and output
vague data.vague -v api.json -o output.json -p

# Watch mode with validation
vague data.vague -v api.json -o output.json -w

Multiple Specs​

Validate different collections against different specs:

# Validate orders against orders-api.json
vague orders.vague -v orders-api.json -m '{"orders": "Order"}'

# Validate users against users-api.json
vague users.vague -v users-api.json -m '{"users": "User"}'

Validation Rules​

Vague validates against:

OpenAPI ConstraintValidation
type: string/number/etcType checking
required: [fields]Required field presence
enum: [values]Value in allowed set
minimum/maximumNumeric bounds
minLength/maxLengthString length
patternRegex matching
format: email/uuid/etcFormat validation
$refReferenced schema

Handling Validation Errors​

Constraint Conflicts​

If your Vague schema can produce values that violate OpenAPI constraints:

schema Invoice {
  // Vague allows 0, but OpenAPI requires > 0
  amount: int in 0..1000,
  assume amount >= 0  // Should be > 0
}

Fix by tightening Vague constraints:

schema Invoice {
  amount: int in 1..1000  // Now always > 0
}

Missing Fields​

If OpenAPI requires a field:

# openapi.yaml
Invoice:
  required: [id, amount, status]

Ensure your Vague schema includes it:

schema Invoice {
  id: uuid(),
  amount: decimal in 100..1000,
  status: "draft" | "paid"  // All required fields present
}

Format Mismatches​

If OpenAPI expects a specific format:

# openapi.yaml
email:
  type: string
  format: email

Use the appropriate generator:

schema User {
  email: email()  // Generates valid emails
}

Programmatic Validation​

import { fromFile, validate } from 'vague-lang';

const data = await fromFile('./data.vague');
const result = await validate(data, './openapi.json', {
  mapping: { invoices: 'Invoice' }
});

if (!result.valid) {
  console.error('Validation errors:', result.errors);
}

See Also​