ajv

Postconditions — what we check

• validate · validate-returns-false

  error
  Whendata fails validation against the JSON schema
  Returnsfalse (errors are stored in ajv.errors property)
  Required handlingCaller MUST check the return value of validate() and handle the false case. When validate() returns false, ajv.errors contains validation error details. Without checking the return value, invalid data will pass through, leading to data corruption, business logic errors, or security vulnerabilities. Use pattern: if (!ajv.validate(schema, data)) { console.error(ajv.errors); }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• compile · compile-invalid-schema

  warning
  Whenschema is invalid or malformed
  ThrowsError (schema compilation error)
  Required handlingCaller MUST wrap compile() in try-catch when working with untrusted schemas. Invalid schemas cause compilation errors that crash the application. Use pattern: try { const validate = ajv.compile(schema); } catch (error) { /* handle */ }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• validateSchema · validateschema-returns-false

  warning
  Whenschema is invalid according to meta-schema
  Returnsfalse (errors are stored in ajv.errors property)
  Required handlingCaller MUST check the return value to determine if schema is valid. Without checking, invalid schemas may be used, causing unexpected validation behavior. Use pattern: if (!ajv.validateSchema(schema)) { console.error(ajv.errors); }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• compileAsync · compileasync-no-load-schema

  error
  WhencompileAsync() is called without configuring the loadSchema option in Ajv constructor
  ThrowsError: options.loadSchema should be a function
  Required handlingCaller MUST configure loadSchema in Ajv options before calling compileAsync(). The error throws synchronously before the promise is even created. If the schema has external $ref dependencies, loadSchema is mandatory. Use pattern: new Ajv({ loadSchema: async (uri) => fetch(uri).then(r => r.json()) })
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3][4]
• compileAsync · compileasync-load-schema-rejects

  error
  WhenThe loadSchema function rejects (e.g., remote schema URL returns 404/500, network is unavailable, or the schema server is down)
  ThrowsError (propagated rejection from loadSchema)
  Required handlingCaller MUST await compileAsync() inside a try-catch or attach a .catch() handler. loadSchema failures propagate as promise rejections. In server startup code, unhandled rejections crash Node.js. Cache compiled validators to avoid repeated remote fetches on every request. Use pattern: const validate = await ajv.compileAsync(schema).catch(err => { throw new Error('Schema load failed: ' + err.message); })
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3][4]
• compileAsync · compileasync-invalid-schema

  error
  WhenThe schema (or a schema loaded via loadSchema) is invalid against its meta-schema
  ThrowsError: schema is invalid
  Required handlingCaller MUST wrap compileAsync() in try-catch. Invalid referenced schemas cause the promise to reject with a descriptive Error. Schemas loaded dynamically from external sources should be pre-validated before being returned from loadSchema. Use pattern: try { const validate = await ajv.compileAsync(schema); } catch (e) { handle(e); }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• addSchema · addschema-duplicate-id

  error
  WhenA schema with the same $id or key is added a second time to the same Ajv instance
  ThrowsError: schema with key or id already exists
  Required handlingCaller MUST check if a schema is already registered before calling addSchema(). Duplicate schema registration crashes immediately. This commonly occurs in server code that initializes Ajv in module scope but registers schemas in a function called on every request or startup retry. Use pattern: if (!ajv.getSchema(schema.$id)) { ajv.addSchema(schema); }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• addSchema · addschema-invalid-schema-throws

  warning
  WhenA schema with invalid structure is added and validateSchema option is true (default). Ajv validates the schema against the meta-schema during addSchema().
  ThrowsError: schema is invalid
  Required handlingCaller MUST wrap addSchema() in try-catch when registering schemas from untrusted or external sources. Schema validation errors throw synchronously. If registering known static schemas at startup, errors here indicate a developer mistake and should be allowed to crash (fail-fast). For dynamic schemas from user input, validate first using ajv.validateSchema() before calling addSchema().
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• addKeyword · addkeyword-duplicate-keyword

  error
  WhenaddKeyword() is called with a keyword name that was already registered on this Ajv instance (either a standard JSON Schema keyword or a previously added custom keyword)
  ThrowsError: Keyword <name> is already defined
  Required handlingCaller MUST check if the keyword is already registered before calling addKeyword(). There is no way to redefine or remove keywords once added. Duplicate registration is a common bug in modular server code where multiple modules independently try to register the same shared keyword (e.g., a custom "nullable" keyword registered by two different plugins). Use pattern: if (!ajv.getKeyword(keyword)) { ajv.addKeyword(definition); }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• addKeyword · addkeyword-invalid-name

  warning
  WhenThe keyword name contains invalid characters (must match /^[a-z_$][a-z0-9_$:-]*$/i) or is empty
  ThrowsError: Keyword <name> has invalid name
  Required handlingCaller MUST use valid keyword names starting with ASCII letter, underscore, or dollar sign, containing only alphanumerics, underscores, hyphens, or colons. Use application-specific prefixes to avoid name collisions with future JSON Schema keywords (e.g., "myapp-nullable" instead of "nullable").
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]ajv.js.org/guide/getting-started.htmlhttps://ajv.js.org/guide/getting-started.html#basic-data-validation
2. [2]ajv.js.org/api.htmlhttps://ajv.js.org/api.html#validateschema-schema-object-boolean
3. [3]ajv.js.org/api.htmlhttps://ajv.js.org/api.html#compileAsync
4. [4]ajv.js.org/guide/managing-schemas.htmlhttps://ajv.js.org/guide/managing-schemas.html
5. [5]ajv.js.org/api.htmlhttps://ajv.js.org/api.html#addSchema
6. [6]ajv.js.org/api.htmlhttps://ajv.js.org/api.html#addKeyword