Skip to main content

Invalid Example Values Are Now Removed During Import with Warnings

· 3 min read

We've improved how example values are validated during API import. An example that doesn't match its declared type or format is now removed from the API definition, and a warning tells you exactly where it was found. Previously, some invalid examples slipped through into your SDKs and documentation, while others were removed without any warning.

Heads-up! Behavior Change

If your API definition contains invalid example values, they may have previously carried through to SDK generation and documentation unchanged. After this release, those examples are removed during import and APIMatic may generate a sample value in their place. Your SDKs and docs will still generate, but the examples shown in them may change or disappear. Check the warnings logged during import to find and fix the affected examples in your API definition.

What was happening before​

Example validation during import had gaps. Some invalid examples weren't caught at all, so they ended up as-is in generated SDKs, code samples, and documentation. Others were removed, but no warning was logged, so a different, auto-generated sample appeared in the output with no explanation of why the authored one was gone.

What happens now​

Every invalid example is removed with a warning that names the component it belongs to. An example is considered invalid when, for instance:

  • Its value doesn't match the declared type, such as a number given for a string field.
  • A date value can't be parsed, or is an impossible date like 2026-02-31.
  • A format: byte value isn't valid Base64.
  • An explicit null is given for a field that's not nullable.
  • An array example's nesting doesn't match the declared array dimensions.
  • The example value is empty.

Validation now also covers places it previously missed, including examples on response headers and in callback bodies.

One common authoring mistake is repaired instead of removed: a bare value given as the example for an array of strings, such as example: pending on a string array, is wrapped into an array (["pending"]) and kept.

What you should do​

Valid examples aren't affected, so no action is needed if your examples already match their declared types and formats. If examples disappear from your SDKs or documentation after this release, look through the validation warnings logged during import. Each warning points to the example that was removed, so you can correct its value in your API definition and keep your authored examples in the output.