External Examples

Validating Examples
- Quick Start
- Advanced Usage
  - Working with Multiple Specifications
  - Custom Example Directory
Practical Example
Pro Tips

Learn how to validate your API examples against your specifications using Specmatic’s powerful validation tools. Whether you have a single specification or multiple specs across different directories, Specmatic makes it easy to ensure your examples stay in sync with your API definitions.

Validating Examples

Quick Start

The fastest way to validate examples for a single specification:

docker run -v "$(pwd)/employee_details.yaml:/usr/src/app/employee_details.yaml" -v "$(pwd)/employee_details_examples:/usr/src/app/employee_details_examples" znsio/specmatic examples validate --spec-file "employee_details.yaml"

java -jar specmatic.jar examples validate --spec-file employee_details.yaml

npx specmatic examples validate --spec-file employee_details.yaml

By default, Specmatic looks for examples in a directory named {specification-name}_examples in the same location as your specification file. For instance, if your spec file is named employee_details.yaml, Specmatic will look for examples in the employee_details_examples directory.

Advanced Usage

Working with Multiple Specifications

If you’re managing multiple API specifications, Specmatic provides flexible options to validate all their examples:

Validate Multiple Specs with Default Example Locations:
```
specmatic examples validate --specs-dir ./api-specs
```
This will look for example directories alongside each specification file.
Organize Examples in a Separate Directory Structure:
```
specmatic examples validate --specs-dir ./api-specs --examples-base-dir ./all-examples
```
This helps when you want to keep your examples organized separately from your specifications.

Custom Example Directory

For a single specification, you can specify a custom examples directory:

specmatic examples validate --spec-file employee_details.yaml --examples-dir ./custom-examples

Practical Example

Let’s walk through a complete example to see how example validation works in practice.

Create an API specification file named employee_details.yaml:

openapi: 3.0.0
info:
  title: Employees
  version: '1.0'
servers: []
paths:
  '/employees':
    patch:
      summary: ''
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeeDetails'
      responses:
        '200':
          description: Employee Created Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
components:
  schemas:
    Employee:
      type: object
      required:
        - id
        - name
        - department
        - designation
      properties:
        id:
          type: integer
        employeeCode:
          type: string
        name:
          type: string
        department:
          type: string
        designation:
          type: string

    EmployeeDetails:
      type: object
      required:
        - name
        - department
        - designation
      properties:
        name:
          type: string
        employeeCode:
          type: string

Create an example in employee_details_examples/example.json:

{
    "http-request": {
        "method": "PATCH",
        "path": "/employees",
        "body": {
            "employeeCode": "pqrxyz"
        }
    },
    "http-response": {
        "status": 200,
        "body": {
            "id": 10,
            "employeeCode": "pqrxyz",
            "name": "Jamie",
            "department": "(string)",
            "designation": "(string)"
        }
    }
}

Validate your example:

docker run -v "$(pwd)/employee_details.yaml:/usr/src/app/employee_details.yaml" -v "$(pwd)/employee_details_examples:/usr/src/app/employee_details_examples" znsio/specmatic examples validate --spec-file "employee_details.yaml"

java -jar specmatic.jar examples validate --spec-file employee_details.yaml

npx specmatic examples validate --spec-file employee_details.yaml

You’ll notice the validation fails because the request is missing required fields (name, department, and designation). The error message will guide you to fix these issues.

Check the exit code:
- On MacOS/Linux: echo $?
- On Windows: echo %errorlevel%

A return code of 1 indicates validation failure, while 0 indicates success.

Fix the example by adding the required fields and run the validation again - you’ll see it succeed!

Pro Tips

Use --specs-dir with --examples-base-dir when managing multiple APIs to keep your examples organized
Specmatic automatically finds example directories using the {spec-name}_examples convention (e.g., employee_details_examples for employee_details.yaml)
The validation command will exit with code 1 if any examples are out of sync, making it perfect for CI/CD pipelines

Need more details? Run the help command:

docker run znsio/specmatic examples validate --help

java -jar specmatic.jar examples validate --help

```
npx specmatic examples validate --help
```