jsonschema

Postconditions — what we check

• validate · validate-throw-first

  error
  Whenoptions.throwFirst is set and validation fails
  ThrowsValidatorResultError with validation errors
  Required handlingCaller MUST wrap validate() calls with throwFirst option in try-catch. When throwFirst is set, the validator will throw ValidatorResultError at the first validation error. Without try-catch, invalid data causes unhandled exceptions and application crashes.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• validate · validate-throw-all

  error
  Whenoptions.throwAll is set and validation fails
  ThrowsValidatorResultError with all validation errors
  Required handlingCaller MUST wrap validate() calls with throwAll option in try-catch. When throwAll is set, the validator will collect all validation errors and then throw ValidatorResultError. Without try-catch, invalid data causes unhandled exceptions.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• validate · validate-throw-error

  error
  Whenoptions.throwError is set and validation fails
  ThrowsValidationError at first validation failure
  Required handlingCaller MUST wrap validate() calls with throwError option in try-catch. When throwError is set, the validator will throw ValidationError immediately at the first failure. Without try-catch, invalid data causes unhandled exceptions.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• validate · validate-invalid-schema-argument

  error
  Whenschema argument is null, undefined, a string, number, or other non-object/non-boolean type
  ThrowsSchemaError('Expected `schema` to be an object or boolean')
  Required handlingCaller MUST ensure the schema argument is a valid object or boolean before calling validate(). Passing null, undefined, a string, or any other primitive throws SchemaError synchronously. This commonly occurs when schemas are loaded from external sources (databases, HTTP APIs, config files) without validation of the loaded value. The call site MUST have try-catch or pre-validate the schema.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• validate · validate-unknown-attribute-throws

  warning
  Whenoptions.allowUnknownAttributes is false and schema contains an unrecognized keyword
  ThrowsSchemaError('Unsupported attribute: <key>')
  Required handlingWhen using allowUnknownAttributes:false with externally-provided or dynamic schemas, caller MUST wrap in try-catch. Unknown JSON Schema keywords (custom or future draft keywords not implemented by this library version) cause SchemaError to be thrown synchronously. This is a strict-mode option — callers who set it accept stricter schema validation but must handle the resulting throws.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• validate · validate-result-unchecked

  warning
  Whenvalidate() is called without throw options and the return value's .valid property or .errors array is never inspected
  Throwsnothing — silent data accepted as valid
  Required handlingWhen validate() is called without throwFirst/throwAll/throwError options, it returns a ValidatorResult object. Callers MUST check result.valid (or result.errors.length) before proceeding. If the result is discarded or only used for its instance value without checking validity, invalid data silently passes validation. This is the most common misuse pattern: calling validate() for its side-effects while assuming success. Pattern to avoid: validate(data, schema); // result discarded — data used regardless
  costhighin prodsilent failureusers seelost datavisibilitysilent
  Sources[3][1]
• Validator.validate · validator-validate-throw

  error
  Whenthrow options are set and validation fails
  ThrowsValidatorResultError or ValidationError depending on options
  Required handlingCaller MUST wrap Validator.validate() calls with throw options in try-catch. Same behavior as standalone validate() - throws when throwFirst, throwAll, or throwError options are enabled.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• Validator.validate · validator-validate-unresolved-ref

  error
  Whenschema uses $ref URI that was not pre-registered with addSchema()
  ThrowsSchemaError('no such schema <uri>')
  Required handlingWhen Validator.validate() encounters a $ref in the schema, it resolves the URI against schemas registered with addSchema(). If the referenced schema was never registered, it throws SchemaError synchronously. This occurs in multi-schema setups (OpenAPI/JSON Schema $ref compositions) when a dependent schema is missing. Caller MUST ensure all referenced schemas are registered before calling validate(), and MUST wrap in try-catch when schemas come from external or dynamic sources.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• addSchema · add-schema-invalid

  error
  Whenschema is invalid or undefined
  ThrowsSchemaError when schema definition is invalid
  Required handlingCaller MUST wrap addSchema() calls in try-catch, especially when loading schemas from external sources. Invalid or undefined schemas cause SchemaError, common when loading from databases or HTTP endpoints.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• scan · scan-duplicate-conflicting-schema

  error
  WhenTwo schemas share the same $id or id URI but have different structure/definitions. This occurs when dynamically assembling schema registries from multiple sources (config, database, HTTP) where the same schema ID appears with different content.
  ThrowsError('Schema <uri> already exists with different definition')
  Required handlingCaller MUST wrap scan() in try-catch when processing schemas from external or dynamic sources. The error is thrown as a generic Error (not SchemaError), making it easy to miss in catch(err) blocks that check instanceof SchemaError. Callers should deduplicate schemas before scanning or use a try-catch that catches all Error types.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]

Sources

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

1. [1]github.com/tdegrunt/jsonschemahttps://github.com/tdegrunt/jsonschema/blob/master/README.md
2. [2]github.com/tdegrunt/jsonschemahttps://github.com/tdegrunt/jsonschema/blob/master/lib/validator.js
3. [3]github.com/tdegrunt/jsonschemahttps://github.com/tdegrunt/jsonschema/blob/master/lib/helpers.js
4. [4]github.com/tdegrunt/jsonschemahttps://github.com/tdegrunt/jsonschema/issues/290
5. [5]github.com/tdegrunt/jsonschemahttps://github.com/tdegrunt/jsonschema/blob/master/lib/scan.js