JSON validation

The JSON parser offers high-performance, standards-compliant JSON schema validation at any point in a message flow.

Validation of the input JSON message or the message tree is performed against the JSON schema files or OpenAPI definition files that are deployed. JSON schema must be contained in a file with a .json file extension, and it must either contain schema in the name (for example, .schema.json) or the first line of the file must indicate that it is a schema (for example, "$schema": "http://json-schema.org/draft-04/schema#").

In the following sections, the term JSON schema is used to refer to either a JSON schema file or an OpenAPI definition file.

Validation is not the same as parsing. When parsing, the JSON parser always checks that the input document is well-formed JSON, according to the JSON specification. If validation is enabled, the JSON parser also checks that the JSON document obeys the rules in the JSON schema.

You can use the JSON editor in the IBM® App Connect Enterprise Toolkit to edit JSON files; however, the validation capability of the editor has a number of limitations and must not be used to validate your JSON documents.

Video: JSON Validation

This video demonstrates the capability to validate a JSON message using JSON Schema.

For more videos about JSON validation, see the IBM App Connect Enterprise playlist on YouTube.

Enabling JSON schema validation in a message flow

Complete the following tasks to construct a message flow that validates a JSON document in accordance with a JSON schema:

  • Enable validation at the appropriate point in the message flow, by setting the Validate property of the appropriate node to Content and Value. For more information, see Validating messages. If the message flow is in a REST API project, enable validation by using the REST API editor.
  • Ensure that all required JSON schema files are deployed, as described in Deploying JSON schemas.
  • Supply the name of the JSON schema that contains the definition corresponding to the JSON document. Typically, you specify this by setting the Message model property on a message flow node. If the parser is being invoked from a programming language such as ESQL or Java™, the message model must be specified in the parameters of the function call. If the message flow is in a REST API project, the JSON schema name is set automatically.

To ensure that misspelled and unwanted JSON objects and properties are detected by validation, set the "additionalProperties": "false" property in the JSON schemas.

Deploying JSON schemas

JSON schemas with a .json file extension can be deployed in an application or in a library that is referenced by an application.

If the schemas are deployed as part of the application, they must be included in one of the projects that are referenced by the application.

If the schemas are deployed in a library, the application must reference that library, even if it is deployed as part of a different application.

Standards compliant validation

JSON validation complies with the JSON schema specifications that are shown in the following table, except for the default, format, and discriminator properties, which are ignored:

Other drafts are not supported, and any attempt to use a JSON schema that specifies an unsupported schema draft or OpenAPI version results in a BIP5754 message when the deployed schema is first used.

Interpreting validation errors

A validation error occurs when the JSON document does not conform to the rules that are defined in the JSON schema. The JSON schema specifications specify exactly what these rules are, and how they must be applied. Validation errors that are issued by the JSON parser contain information that links the error to the construct in the JSON schema that was violated.

All validation errors are reported in BIP5751 (parsing) or BIP5752 (writing) messages. Each message contains the following information as inserts:
  • The validation error
  • The location of the error in the JSON message
  • The matching location in the JSON schema file
  • The error context

Both locations are in the form of a JSON pointer into the document (see https://datatracker.ietf.org/doc/html/rfc6901).

For the oneOf, anyOf, allOf, not, and dependencies JSON schema constructs, there is an initial BIP5751 or BIP5752 message, followed by one or more BIP5751 or BIP5752 messages with the error context set to the construct name. For example, if a validation error occurs because a JSON object in the message fails to match any of the items in a oneOf array in the schema, an initial BIP5751 message for the oneOf failure is followed by a BIP5751 message for each item in the oneOf array, explaining why the object failed to match the item, each with error context set to oneOf. Nested oneOf, anyOf, and allOf schema constructs can result in a large number of error messages, as the JSON parser attempts to validate against all the possibilities.

If the JSON schema file does not provide enough information, you can find more information using a search engine. The JSON schema draft standards are very widely used, and many online tutorials and other resources are available.

JSON schema correctness

Deployed JSON schema are checked for well-formedness and validity by parsing them and validating them against the JSON meta-schema file for the relevant JSON schema draft or OpenAPI version. Any violations are reported when the deployed JSON schema is first used by a message flow and causes an exception to occur. If this occurs, you must correct and redeploy the JSON schema.

OpenAPI considerations

When the JSON schema is part of an OpenAPI definition, the following additional considerations apply when validation is enabled and the message flow is not in a REST API project:

  • When the schema model is defined in the top-level OpenAPI definition, the Message property of the node must be specified, and must be a JSON pointer to the schema model in the definition. For example:

    For more information about JSON pointers, see JSON Pointers.

  • When the schema model is defined by a JSON schema file or OpenAPI definition that is referenced by a top-level OpenAPI definition using the $ref schema construct, the Message format property must specify the OpenAPI version that applies. Valid values are Swagger 2.0 definition or OpenAPI 3.0 definition.

When the message flow is in a REST API project, these properties are set automatically.

The JSON models for REST API responses are typically provided in the Swagger definitions or OpenAPI 3 components/schemas section of the OpenAPI definition, and it is often simpler to specify the JSON path to that section directly. For example, the standard Pets Store Swagger 2 example operation "getPetById" defines its response as "schema" : { "$ref" : "#/definitions/Pet" }, so you can use the simple JSON pointer "/definitions/Pet" directly in the Message property on the RESTRequest node.

In the Response Message Parsing tab of the RESTRequest node, set the following properties:
  • Deselect Automatic Content type handling
  • Set Message Domain to JSON
  • Set Message model to the OpenAPI document name
  • Set Message to the JSON path for the relevant model

For example:

The image is described in the surrounding text.

The more complex JSON pointer for this would be "/paths/~1pet~1{petId}/get/responses/200/schema". When any part of the JSON path contains a "/", it must be escaped as "~1", which means that the getPetById operation's path "/pet/{getId}" would be "~1pet~1{petId}".

Video: JSON Validation, using an OpenAPI document

This video demonstrates how you can configure a RESTRequest node to validate a JSON response message from a back-end REST API.

For more videos about JSON validation, see the IBM App Connect Enterprise playlist on YouTube.