Contract

The Contract tab validates API responses against a JSON Schema. This ensures the server returns data in the expected format, catching breaking changes and bugs early. You can either define a custom schema for standalone requests or use schemas from your OpenAPI project definitions.

Validation Modes

The Contract tab operates in two modes depending on the request source:

Custom Schema Mode

For standalone requests (not from a project). You manually define a JSON Schema to validate responses.

Project Mode

For requests from an OpenAPI project. Uses expected responses defined in your project's endpoint specification.

Custom Schema Mode

When working with standalone requests (not from a project), you can add a custom JSON Schema to validate responses:

Initial State

Contract Validation

Add a custom JSON Schema to validate responses, or save this request to a project for full contract validation.

Add Schema
Schema Editor

Click "Add Schema" to open the schema editor. You can paste JSON Schema directly or upload a .json file:

{"type": "object", "properties": {...}}
Upload JSON
CancelSave Schema
Example Schema
{
  "type": "object",
  "required": ["id", "name", "email"],
  "properties": {
    "id": {
      "type": "integer",
      "minimum": 1
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    }
  }
}
File Upload: You can upload a .json file containing your schema. Maximum file size is 1 MB.

Project Mode

When a request is opened from an OpenAPI project, the Contract tab uses the expected responses defined in your endpoint specification:

Expected Responses

Shows all responses defined in the OpenAPI spec for this endpoint:

200Successful responseCurrent
application/json→User
400Bad request
application/json→Error
500Internal server error
Actual Response

Shows the current response summary for comparison:

200OK
Content-Type:application/json
Size:1,234 bytes

Validation Results

The validation result shows whether the response matches the expected schema:

Response matches contract

Response status code, content type, and body all match the expected schema.

Warning — matched the "default" response

The actual status code is not listed explicitly in the spec, but the spec defines a default response that was used as the fallback contract. Atrahasis flags this so you notice when a code you expected to be explicit is silently falling through to the catch-all.

Warning — status code not defined in the contract

The actual status code is not in the spec's expected responses, and the spec does not define a default response either. Atrahasis cannot validate the body against anything in this case and surfaces a warning instead of an error — the response might still be valid, you just have no contract to check it against.

Schema validation failed (3 errors)

Response body doesn't match the expected schema structure.

Schema Validation Errors

When validation fails, detailed errors are shown to help identify the mismatch:

Validation Errors

/users/0/emailmust match format "email"
Expected:email format
Actual:"not-an-email"
/users/0/agemust be integer
Expected:integer
Actual:string

... and 1 more error

Error Path: The JSON path (e.g., /users/0/email) shows exactly where in the response the error occurred. Use this to quickly locate the problematic data.

Content Type Validation

In addition to schema validation, the Contract tab also checks:

CheckWhat's ValidatedOn Mismatch
Status CodeResponse status matches one of the defined expected responses (or the default response as a fallback).Warning
Content-TypeActual response Content-Type is one of the media types declared for the matched status code.Error — the entire contract check fails with an error state, body schema validation is not attempted.
Body SchemaResponse body structure matches the JSON Schema (for JSON responses). Only runs after the Status Code and Content-Type checks pass.Error
Non-JSON Responses: When the response content type is not JSON (XML, HTML, plain text, binary), body-level schema validation is skipped because there is no JSON structure to match against the schema. In this case the validation badge is rendered as success (green check), and the result message reads Schema validation skipped (non-JSON response) to make the skip explicit. The green badge does not mean "the body matches the schema" — it means "nothing was checked at the body level, and the other checks (status code, content type) did not fail."

Schema References

In Project Mode, schemas can be defined in two ways:

inlineInline Schema

Schema is defined directly in the endpoint's response specification.

UserReferenced Schema

Schema references a shared component defined in the project's components/schemas section.

$ref Resolution: Atrahasis automatically resolves $ref references to their full schema definitions, including nested references within schemas.
DetailScripting API Overview