Copy page

Guides

OpenAPI Format Validation Warnings in Local Development

When you run a Zuplo project locally with npm run dev (or zuplo dev), the console may print one or more warnings like this:

Code
unknown format "date-time" ignored in schema at path "#/properties/createdAt"

These warnings are informational. They do not stop the development server, fail schema validation, or change how your gateway behaves once deployed. This page explains what the warning means and what, if anything, to do about it.

What the warning means

Zuplo validates requests against your OpenAPI schema using Ajv, a standard JSON Schema validator. In JSON Schema and OpenAPI, the format keyword (for example date-time, email, or uuid) is an annotation. A validator only enforces a format if it has a validator registered for that specific format. For any format it does not recognize, the standard behavior is to skip the format check and log a message like the one above.

When you see unknown format "date-time" ignored in schema at path "…", it means:

• The validator found a format: "date-time" (or similar) in your schema.
• It has no registered check for that format in local development, so it ignores the format and moves on.
• The field is still validated against its type and any other keywords you set, such as pattern, enum, minimum, maxLength, or required.

The path in the message (for example #/properties/createdAt, or a path or query parameter location) points to where the format appears in the schema, so you can locate it.

Are the warnings safe to ignore?

Yes. The warning is purely informational. It does not:

• Stop or crash the local development server.
• Cause a build or deployment to fail.
• Reject any request, or change the response your API returns.
• Change validation behavior in deployed environments.

Type checking and every other constraint in your schema continue to work exactly as written. An enforced format validates the shape of a value — for example, that a string looks like an RFC 3339 date-time. When a format is ignored, you lose only that one extra check; the field's type and all other constraints are unaffected.

Why some formats warn and others don't

You may notice the warning for some formats but not others, and on some fields but not others. A few things drive this:

• format is advisory in JSON Schema. Validators are free to enforce only the formats they choose to register. Which formats are actively checked is an internal detail of the validator and can differ between CLI versions, so treat the set as subject to change rather than a fixed contract.
• Path and query parameters are validated separately from request bodies. Parameter schemas and body schemas are generally compiled independently, so the same format can produce a warning in one place but not the other.

Because the warning is harmless, you do not need to determine exactly which formats are checked. The guidance below applies to any format that warns.

How to remove the warnings

You have two options, depending on whether you rely on that format for validation.

Option 1 — Leave the format keyword in place (recommended). Keeping format annotations is good practice: they document intent, drive code generation and the developer portal, and are useful to consumers of your API even when the gateway does not enforce them. The warning is the only cost, and it is cosmetic.

Option 2 — Enforce the value with a constraint that is checked. If you want the gateway to actively reject malformed values, replace or supplement the format with explicit constraints that the validator always enforces, such as pattern, enum, minLength/maxLength, or minimum/maximum. For example, to enforce a date-time-like string with a regular expression instead of relying on format:

Code
{
  "createdAt": {
    "type": "string",
    "format": "date-time",
    "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$"
  }
}

Here format stays for documentation, and pattern does the actual enforcement. The regular expression above is an illustrative RFC 3339-style example, not a Zuplo-mandated pattern — adjust it to match the values you expect. The warning may still appear for the ignored format, but the value is now strictly validated.

Related

• Request Validation Policy — validate request bodies, query parameters, path parameters, and headers against your OpenAPI schema.
• Schema Validation Failed (SCHEMA_VALIDATION_FAILED) — the runtime error returned when a request does not pass schema validation.
• OpenAPI Support in Zuplo — how Zuplo uses your OpenAPI document to configure the gateway.
• Local Development — run and test your gateway locally with the Zuplo CLI.