Validate service definition files to ensure they are correctly formatted and contain valid configurations before using them with the simulator.
Usage
apicentric simulator validate [OPTIONS] --file <PATH>
Arguments
Path to a service definition file or directory to validate. Can be a single YAML file or a directory containing multiple service definitions.
Options
Recursively search subdirectories for YAML files when validating a directory. Finds all service definitions in nested folder structures.
Display detailed validation results for each file, including success messages. Without this flag, only errors are shown.
--config
string
default:"apicentric.json"
Path to the configuration file (global option).
Execution mode override: ci, development, or debug (global option).
Show what would be validated without actually performing validation (global option).
--db-path
string
default:"apicentric.db"
Path to the SQLite database for simulator storage (global option).
Examples
Validate a single file
apicentric simulator validate --file ./services/users.yaml
🔍 Validating service definitions...
📁 Path: ./services/users.yaml
📊 Validation Results: total=1 valid=1 invalid=0
✅ All files valid
🔍 Validating service definitions...
📁 Path: ./services/users.yaml
❌ missing required field 'server.port' at line 5
📊 Validation Results: total=1 valid=0 invalid=1
Validate a directory
apicentric simulator validate --file ./services
./services directory.
Example output:
🔍 Validating service definitions...
📁 Path: ./services
📊 Validation Results: total=5 valid=4 invalid=1
Validate recursively with verbose output
apicentric simulator validate --file ./services --recursive --verbose
🔍 Validating service definitions...
📁 Path: ./services
🔎 ./services/users.yaml
✅ valid
🔎 ./services/products.yaml
✅ valid
🔎 ./services/orders.yaml
❌ invalid endpoint method 'FETCH' at line 12
🔎 ./services/nested/payments.yaml
✅ valid
📊 Validation Results: total=4 valid=3 invalid=1
Dry run mode
apicentric simulator validate --file ./services --dry-run
🏃 Dry run: Would validate service definitions (path=./services, recursive=false, verbose=false)
What gets validated
The validation command checks:
- YAML syntax - Proper formatting and structure
- Required fields - Presence of mandatory configuration keys
- Schema compliance - Correct data types and field names
- Server configuration - Valid port numbers and base paths
- Endpoint definitions - Valid HTTP methods, routes, and response codes
- Response structures - Proper JSON schema in response bodies
- Data type definitions - Valid type schemas and references
Validation happens automatically when you start the simulator, but running this command beforehand helps catch errors early in development.
Use cases
Pre-commit validation
Add to your Git pre-commit hook:
#!/bin/bash
apicentric simulator validate --file ./services --recursive
if [ $? -ne 0 ]; then
echo "Service validation failed. Fix errors before committing."
exit 1
fi
CI/CD pipeline
# GitHub Actions example
- name: Validate service definitions
run: apicentric simulator validate --file ./services --recursive
Development workflow
# Validate before starting
apicentric simulator validate --file ./services --verbose && \
apicentric simulator start --services-dir ./services
Common validation errors
Missing required fields
❌ missing required field 'server.port' at line 5
Invalid HTTP method
❌ invalid endpoint method 'FETCH' at line 12
YAML syntax errors
❌ YAML parse error: expected mapping at line 10
If validation fails for any file, the command exits with a non-zero status code. This makes it suitable for use in CI/CD pipelines where validation failures should block deployment.
Exit codes
0 - All files are valid- Non-zero - One or more files failed validation