Skip to main content

Parameters and Schemas

Parameters and schemas make your proxies self-documenting and consumer-friendly. They power the Developer Portal testing console, the OpenAPI export, and optional request validation.

Parameters​

Parameters describe the inputs a proxy accepts. They are displayed in the portal endpoint detail and included in the OpenAPI spec.

Parameter fields​

FieldDescription
NameIdentifier used in the path template or query string
Inpath — part of the URL path; query — appended to the URL
Typestring, integer, number, boolean
RequiredPath parameters are always required; query parameters are optional by default
DescriptionConsumer-facing description shown in portal
DefaultDefault value used when the parameter is omitted (query only)
EnumAllowed values list — restricts input to a defined set

Path parameters​

Use {paramName} in the path to define a path parameter:

Path:   /v1/charges/{chargeId}
Target: /charges/{chargeId}

Define chargeId as a path parameter of type string, required: true.

Query parameters​

Query parameters are appended to the URL:

GET /v1/charges?limit=10&cursor=abc123

Define limit as an integer, required: false, default: 20. Define cursor as a string, required: false.

Enum parameters​

When you define an enum list on a parameter, the Developer Portal testing console renders it as a dropdown:

parameters:
  - name: status
    in: query
    type: string
    enum: [pending, completed, failed, refunded]

This prevents consumers from sending invalid values and speeds up testing.

Schemas​

Schemas define the shape of request and response bodies using JSON Schema draft-07.

Request schema​

Zerq validates inbound request bodies against the request schema. Requests that do not match return 400 Bad Request with a validation error message.

Example request schema for a charge creation endpoint:

{
  "type": "object",
  "required": ["amount", "currency"],
  "properties": {
    "amount": {
      "type": "integer",
      "description": "Amount in smallest currency unit (e.g. cents)",
      "minimum": 1
    },
    "currency": {
      "type": "string",
      "enum": ["USD", "EUR", "GBP"],
      "description": "ISO 4217 currency code"
    },
    "description": {
      "type": "string",
      "maxLength": 255
    }
  }
}

Response schema​

Response schemas are documentation-only — they are not used for validation. They appear in:

  • Developer Portal endpoint detail page
  • Generated OpenAPI 3.0/3.1 specification

Examples​

Add concrete examples alongside schemas to give consumers copy-paste request bodies:

Request example:

{
  "amount": 2999,
  "currency": "USD",
  "description": "Subscription plan upgrade"
}

Response example:

{
  "id": "ch_abc123",
  "amount": 2999,
  "currency": "USD",
  "status": "pending",
  "created_at": "2024-01-15T10:00:00Z"
}

OpenAPI export​

All parameters, schemas, and examples are included in the generated OpenAPI specification. Zerq exports both OpenAPI 3.0 and OpenAPI 3.1 formats — the version choice affects which JSON Schema keywords are supported:

  • 3.0 — uses a restricted subset of JSON Schema draft-07
  • 3.1 — full JSON Schema draft 2020-12 support (unevaluatedProperties, $defs, etc.)

Download from the collection detail page or the Developer Portal.