# 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:

```text
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.

:::tip

**Short answer: the warnings are safe to ignore.** They report that a `format`
keyword in your OpenAPI document is not being actively checked — the field is
still validated against its `type` and every other constraint you defined.

:::

## What the warning means

Zuplo validates requests against your OpenAPI schema using
[Ajv](https://ajv.js.org/), a standard JSON Schema validator. In JSON Schema and
OpenAPI, the
[`format` keyword](https://json-schema.org/understanding-json-schema/reference/string#format)
(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`:

```json
{
  "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.

:::caution

The [Request Validation policy](../policies/request-validation-inbound.mdx)
options control _what_ is validated (`validateBody`, `validateQueryParameters`,
`validatePathParameters`, `validateHeaders`) and how failures are handled, but
they do not let you register additional formats or silence individual format
warnings. To guarantee a value's shape, use enforced constraints like `pattern`
as shown above.

:::

## Related

- [Request Validation Policy](../policies/request-validation-inbound.mdx) —
  validate request bodies, query parameters, path parameters, and headers
  against your OpenAPI schema.
- [Schema Validation Failed (SCHEMA_VALIDATION_FAILED)](../errors/schema-validation-failed.mdx)
  — the runtime error returned when a request does not pass schema validation.
- [OpenAPI Support in Zuplo](./openapi.mdx) — how Zuplo uses your OpenAPI
  document to configure the gateway.
- [Local Development](./local-development.mdx) — run and test your gateway
  locally with the Zuplo CLI.