JSON validation

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.

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:

  "/paths/~1customers/get/responses/200/content/application~1json/schema

  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.

For example:

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}".

For a demonstration of how you can configure a RESTRequest node to validate a JSON response message from a back-end REST API, see the following video: JSON validation using an OpenAPI document.

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