# mulesoft JSON Module - Full Documentation

<!-- document id=ebe2c1bec2c5ccf791bf7ba950d882ec7b0ff5d456a511db703fd39fd1fb6350 url=/mulesoft/current/en-us/json-module/latest/index.md -->

---
product: JSON Module
version: 2.5
is-latest-version: true
---

# JSON Module

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

JSON Module v2.5

The JSON module provides extra functionality for processing JSON documents. Although DataWeave is
the tool that Mule uses to access data in JSON documents, this module provides extra functionality
that falls outside of DataWeave’s scope, like schema validation.

Release Notes:
[JSON Module Release Notes](https://docs.mulesoft.com/release-notes/connector/json-module-release-notes)  
Exchange: [JSON Module](https://www.mulesoft.com/exchange/org.mule.modules/mule-json-module/)

## See Also

- [ValidateDocuments against a JSON Schema with the JSON Module](https://docs.mulesoft.com/json-module/latest/json-schema-validation)

- [JSON Module Reference](https://docs.mulesoft.com/json-module/latest/json-reference)

- [Salesforce Help](https://help.salesforce.com)

<!-- document id=b9d7e1b0f3f0be4ebb2f05670c6d1b8eea8ed18385ccffe413c9d0135da14b34 url=/mulesoft/current/en-us/json-module/latest/json-reference.md -->

---
product: JSON Module
version: 2.5
is-latest-version: true
---

# JSON Module Reference

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

JSON Module v2.5

The JSON module provides extra functionality for processing JSON documents. Although DataWeave is
the tool that Mule uses to access data in JSON documents, this module provides extra functionality
that falls outside of DataWeave’s scope, like schema validation.

Release Notes: [JSON Module Release Notes](https://docs.mulesoft.com/release-notes/connector/json-module-release-notes)

## Configurations

---

### Default Configuration

Default configuration

#### Parameters

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Name</th><th>Type</th><th>Description</th><th>Default Value</th><th>Required</th></tr></thead><tbody><tr><td><p>Name</p></td><td><p>String</p></td><td><p>The name for this configuration. Connectors reference the configuration with this name.</p></td><td></td><td><p>x</p></td></tr></tbody></table>

## Operations

### Validate Schema

`<json:validate-schema>`

Validates that the input content is compliant with a given schema. This operation supports
referencing many schemas (using comma as a separator) which include each other.

This operation supports schema versions Draft 3, Draft 4, Draft 6, Draft 7, Draft 2019-09, and Draft
2020-12. If you don’t specify a draft version in the JSON schema node (using the `$schema` keyword),
the default version is Draft 04.

> [!NOTE] Draft 06 and later are handled by a different validation engine than Draft 03 and
> Draft 04. When validation fails, the Draft 03 or Draft 04 engine collects every constraint
> violation across the entire document into the error report, so validating a large payload that
> fails can produce a very large report and cause high transient memory usage.
>
> If you validate large payloads and your schema doesn’t require Draft 03 or Draft 04 specific
> behavior, declare a Draft 06 or later `$schema` (for example,
> `"$schema": "http://json-schema.org/draft-07/schema#"`) so that validation uses the more
> memory-efficient engine.
>
> Schemas generated from RAML typically omit `$schema` and therefore default to the Draft 04 path.

#### Parameters

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Name</th><th>Type</th><th>Description</th><th>Default Value</th><th>Required</th></tr></thead><tbody><tr><td><p>Content</p></td><td><div><div><p>Any</p></div></div></td><td><p>The JSON document to validate.</p></td><td><p>#[payload]</p></td><td></td></tr><tr><td><p>Schema Redirects</p></td><td><div><div><p>Array of <a href="#SchemaRedirect">Schema Redirect</a></p></div></div></td><td><p>Allows to redirect any given URI in the Schema (or even the schema location itself) to any other specific URI. The most common use case for this feature is to map external namespace URIs without the need to a local resource.</p></td><td></td><td></td></tr><tr><td><p>Dereferencing</p></td><td><div><div><p>Enumeration, one of: <strong>CANONICAL </strong>INLINE</p></div></div></td><td><p>Draft v4 defines two dereferencing modes: canonical and inline. CANONICAL is the default option, you can also specify INLINE. This field affects only when you use Draft v4.</p></td><td><p>CANONICAL</p></td><td></td></tr><tr><td><p>Allow Duplicate Keys</p></td><td><div><div><p>Boolean</p></div></div></td><td><p>If true, the validator allows duplicate keys, otherwise it fails</p></td><td><p>true</p></td><td></td></tr><tr><td><p>Allow Arbitrary Precision</p></td><td><div><div><p>Boolean</p></div></div></td><td><p>If true, the validator uses arbitrary precision when reading floating point values, otherwise it uses double precision.</p></td><td><p>false</p></td><td></td></tr><tr><td><p>Schema</p></td><td><div><div><p>String</p></div></div></td><td><p>The location of the validate schema to validate. This attribute supports URI representations such as "http://org.mule/schema.json" or "resource:/schema.json". It also supports a most common classpath reference such as simply "schema.json".</p></td><td></td><td></td></tr><tr><td><p>SchemaContent</p></td><td><div><div><p>String</p></div></div></td><td><p>The content of the schema to validate in text format.</p></td><td></td><td></td></tr></tbody></table>

#### Throws

- JSON:INVALID\_INPUT\_JSON

- JSON:INVALID\_SCHEMA

- JSON:SCHEMA\_NOT\_FOUND

- JSON:SCHEMA\_NOT\_HONOURED

- JSON:SCHEMA\_INPUT\_ERROR

## Types

### Schema Redirect

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Field</th><th>Type</th><th>Description</th><th>Default Value</th><th>Required</th></tr></thead><tbody><tr><td><p>From</p></td><td><div><div><p>String</p></div></div></td><td><p>The original location</p></td><td></td><td><p>x</p></td></tr><tr><td><p>To</p></td><td><div><div><p>String</p></div></div></td><td><p>The redirection location</p></td><td></td><td><p>x</p></td></tr></tbody></table>

## See Also

[Salesforce Help](https://help.salesforce.com)

<!-- document id=81c397450e1c37310612f612376f6968fe729ff5a599707e90f6619379e53caf url=/mulesoft/current/en-us/json-module/latest/json-xml-maven.md -->

---
product: JSON Module
version: 2.5
is-latest-version: true
---

# JSON Module XML and Maven Support

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Although you can manually code a Mule app in XML, it is more efficient to use Anypoint Studio.

If you manually code a Mule runtime engine (Mule) app in XML, either from the Anypoint Studio XML
editor or from a text editor, you can get access to the connector in your app by adding reference
statements to both your XML Mule flow and the Apache Maven `pom.xml` file.

When you add the connector in Studio, Studio automatically populates the XML code with the
connector’s namespace and schema location. It also adds a dependency to the `pom.xml` file.

## Add a Namespace for the Connector

Paste the following code inside the `<mule>` tag of the header of your configuration XML:

```xml
http://www.mulesoft.org/schema/mule/json
http://www.mulesoft.org/schema/mule/json/current/mule-json.xsd
```

This example shows how the namespace statements are placed in the `<mule>` XML block:

```xml
<mule xmlns:json="http://www.mulesoft.org/schema/mule/json"
	xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core"
	xmlns:http="http://www.mulesoft.org/schema/mule/http"
	xmlns:file="http://www.mulesoft.org/schema/mule/file"
	xmlns="http://www.mulesoft.org/schema/mule/core"
	xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.mulesoft.org/schema/mule/core
	http://www.mulesoft.org/schema/mule/core/current/mule.xsd
	http://www.mulesoft.org/schema/mule/file
	http://www.mulesoft.org/schema/mule/file/current/mule-file.xsd
	http://www.mulesoft.org/schema/mule/http
	http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
	http://www.mulesoft.org/schema/mule/ee/core
	http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd
	http://www.mulesoft.org/schema/mule/json
	http://www.mulesoft.org/schema/mule/json/current/mule-json.xsd">
```

## Add a POM File Dependency

The Apache Maven `pom.xml` file generated by Anypoint Studio contains dependencies for a Mule app.
If you code a Mule app manually, include this XML snippet in your `pom.xml` file to enable access to
this connector:

```xml
<dependency>
  <groupId>org.mule.modules</groupId>
  <artifactId>mule-json-module</artifactId>
  <version>x.x.x</version>
  <classifier>mule-plugin</classifier>
</dependency>
```

Replace `x.x.x` with the version that corresponds to the connector you are using.

To obtain the most up-to-date `pom.xml` file information:

1.  Go to [Anypoint Exchange](https://www.mulesoft.com/exchange/).

2.  In Exchange, click **Login** and supply your Anypoint Platform username and password.

3.  In Exchange, search for `json module`.

4.  Select the connector.

5.  Click **Dependency Snippets** near the upper right of the screen.

## See Also

- [Introduction to Anypoint Connectors](https://docs.mulesoft.com/connectors/introduction/introduction-to-anypoint-connectors)

- [Salesforce Help](https://help.salesforce.com)

<!-- document id=ca1475ed4198ef3912019cea958b61a50ac2fe722450104f4108eb0e0c5fb928 url=/mulesoft/current/en-us/json-module/latest/json-module-troubleshooting.md -->

---
product: JSON Module
version: 2.5
is-latest-version: true
---

# Troubleshooting JSON Module

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To troubleshoot JSON module, become familiar with the information about enabling verbose logging and
interpreting commonly thrown messages.

## Enable Verbose Logging

To get a better understanding of why an application’s interaction with the JSON module is failing,
temporarily enable verbose logging for the module.

Remember to always disable the enhanced verbosity after troubleshooting, because it affects your
Mule application performance.

To enable verbose logging in the configuration file:

1.  Access Anypoint Studio and navigate to the **Package Explorer** view.

2.  Open your application’s project name.

3.  Open the `src/main/resources` path folder.

4.  Open the `log4j2.xml` file inside the folder.

5.  Add an `<AsyncLogger>` tag inside the `<Loggers>` tag:

    ```xml
    <Loggers>
    	...
    	<AsyncLogger name="org.mule.module.json" level="DEBUG"/>
    	...
    </Loggers>
    ```

6.  Save your application changes.

7.  Click the project name in **Package Explorer** and then click **Run** > **Run As** > **Mule
    Application**.

## Troubleshoot an Invalid JSON Payload with Trailing Characters

The JSON module **Validate schema** operation now correctly detects an invalid JSON payload with
trailing characters.

To do so, you must add the system property `-DjsonSchemaValidator.FailOnTrailingTokens=true` to the
validation, as it is not a default behavior in the Jackson library used in the connector.

1.  In Studio, navigate to **Run > Run configurations…​**

2.  In the **Run Configurations** screen, select **Mule Applications** from the first column.

3.  Click the **(X)= Arguments** tab.

4.  In the **VM arguments** box, add the system property
    `-DjsonSchemaValidator.FailOnTrailingTokens=true`.

![The system property added in the VM arguments box](/mulesoft/current/en-us/json-module/latest/_images/json-system.png)

## Understand Common Throws

Here is a list of common throw messages and how to interpret them:

- JSON:INVALID\_INPUT\_JSON

  The input document is not valid JSON.

- JSON:INVALID\_SCHEMA

  The supplied schema is invalid.

- JSON:SCHEMA\_NOT\_FOUND

  The schema could not be found.

- JSON:SCHEMA\_NOT\_HONOURED

  The input JSON document does not adhere to its schema.

- JSON:SCHEMA\_INPUT\_ERROR

  The Validate schema operation failed because both the Schema and the SchemaContent fields were
  used at the same time during the operation's execution. You can only use one of these fields to
  validate schema XSD content.

## See Also

- [JSON Module Reference](https://docs.mulesoft.com/json-module/latest/json-reference)

- [Salesforce Help](https://help.salesforce.com)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=71a08e97e264d6658f4963fc63e866331ed8f0d38f8f24b992eada1908637391 url=/mulesoft/current/en-us/json-module/latest/json-schema-validation.md -->

---
product: JSON Module
version: 2.5
is-latest-version: true
---

# Validating Documents Against a JSON Schema with the JSON Module

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The JSON module **Validate schema** operation (`<json:validate-schema>`) validates that the input
content is compliant with a given JSON schema.

> [!NOTE] Supported schema versions are: Draft 3, Draft 4, Draft 6, Draft 7, Draft 2019-09 and Draft
> 2020-12. Drafts 3 and 4 have a different payload response than the other drafts. The operation can
> encounter memory constraints when loading extensive JSON file.

## Configure Validate Schema Operation in Studio

The **Validate schema** operation looks for the input document at the message payload level.
However, you can supply your own input as well. To validate your schema content, you only provide
either schema or schema content, but not both. You can either upload your file in the **Schema**
field, or manually add the direct schema text content in the **Schema content** field. The following
example shows how to configure the operation in Anypoint Studio:

1.  In your Studio flow, drag the File **Read** operation to the canvas.

2.  Set **Path** to `document.json`.

3.  Set **Target** to `jsonDoc`.

4.  Drag the **Validate schema** operation along side the **Read** operation.

5.  Set **Schema** to `/schema/my-schema.json`.

In the **Configuration XML** editor, the `<json:validate-schema>` configuration looks like this:

```xml
<flow name="process">
    <file:read path="document.json" target="jsonDoc" />
    <json:validate-schema schema="/schema/my-schema.json">
    </json:module:validate-schema>
</flow>
```

Note that you can use the **Validate schema** operation (`<json:validate-schema>`) inside a
Validation module **All** operation (`<validation:all>`).

### Configure Schema Content

In the following example, you configure the **Schema Content** field of the **Validate schema**
operation. Enter in this field the schema text content to validate.

> [!NOTE] To add your schema content, you only provide either schema or schema content, but not
> both. You can either upload your file in the **Schema** field, or manually add the direct schema
> text content in the **Schema content** field.

1.  In Studio, select the **Validate Schema** operation from your flow.

2.  In the **Schema Content** field, enter the schema content to validate, for example:

```xml
{
   “$schema”: “http://json-schema.org/draft-04/schema#”,
   “type”: “array”,
   “items”: {
    “type”: “object”,
    “properties”: {
     “a”: {
      “type”: “string”,
      “minLength”: 0,
      “maxLength”: 255
      },
     “b”: {
      “type”: “string”,
      “minLength”: 0,
      “maxLength”: 255
     }
    },
    “not”: {“required”:[“c”]}
   }
  }
```

![Schema content field set to the schema content to validate](/mulesoft/current/en-us/json-module/latest/_images/json-schema-content-1.png)

## Handling a Validation Error

If the validation is successful, the flow continues to the next operation. If the validation fails,
the Mule app returns a `JSON:SCHEMA_NOT_HONOURED` error. The validation can fail because of a number
of reasons, such as the input JSON document does not adhere to its schema. The error description
contains a JSON array of objects. Each of those objects contain information about each found error.

For example, consider the following JSON input:

Invalid JSON

```json
[{ "a": "", "b": "" }, { "a": "", "b": "" }, { "a": "" }, { "a": "", "b": "" }, { "b": "" }]
```

Also, consider the following JSON schema:

JSON Schema

```json
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "a": {
        "type": "string",
        "minLength": 1,
        "maxLength": 255
      },
      "b": {
        "type": "string",
        "minLength": 1,
        "maxLength": 255
      }
    },
    "required": ["a", "b"]
  }
}
```

The input JSON is invalid because both `a` and `b` string attributes are required ("required":
\["a", "b"\]). Both string attributes need to be of at least one character long.

JSON module provides a detailed error response that returns an array of validation errors.
Additionally, if the validation fails, you can append the report to a file, by using the File
**Write** operation as follows :

```xml
<flow name="validate">
    <try>
        <json:validate-schema schema="/schema/object-array-schema.json" />
        <error-handler>
            <on-error-propagate type="JSON:SCHEMA_NOT_HONOURED">
                <file:write config-ref="file" path="errors/jsonSchemas.json" mode="APPEND">
                    <file:content>#[error.errorMessage.payload]</file:content>
                </file:write>
            </on-error-propagate>
        </error-handler>
    </try>
</flow>
```

The following JSON content shows the array of validation errors added to the report file:

```json
[
  {
    "level": "error",
    "schema": {
      "loadingURI": "file:/schema/object-array-schema.json#",
      "pointer": "/items/properties/a"
    },
    "instance": {
      "pointer": "/0/a"
    },
    "domain": "validation",
    "keyword": "minLength",
    "message": "string \"\" is too short (length: 0, required minimum: 1)",
    "value": "",
    "found": 0,
    "minLength": 1
  },
  {
    "level": "error",
    "schema": {
      "loadingURI": "file:/schema/object-array-schema.json#",
      "pointer": "/items/properties/b"
    },
    "instance": {
      "pointer": "/0/b"
    },
    "domain": "validation",
    "keyword": "minLength",
    "message": "string \"\" is too short (length: 0, required minimum: 1)",
    "value": "",
    "found": 0,
    "minLength": 1
  },
  {
    "level": "error",
    "schema": {
      "loadingURI": "file:/schema/object-array-schema.json#",
      "pointer": "/items/properties/a"
    },
    "instance": {
      "pointer": "/1/a"
    },
    "domain": "validation",
    "keyword": "minLength",
    "message": "string \"\" is too short (length: 0, required minimum: 1)",
    "value": "",
    "found": 0,
    "minLength": 1
  },
  {
    "level": "error",
    "schema": {
      "loadingURI": "file:/schema/object-array-schema.json#",
      "pointer": "/items/properties/b"
    },
    "instance": {
      "pointer": "/1/b"
    },
    "domain": "validation",
    "keyword": "minLength",
    "message": "string \"\" is too short (length: 0, required minimum: 1)",
    "value": "",
    "found": 0,
    "minLength": 1
  },
  {
    "level": "error",
    "schema": {
      "loadingURI": "file:/schema/object-array-schema.json#",
      "pointer": "/items"
    },
    "instance": {
      "pointer": "/2"
    },
    "domain": "validation",
    "keyword": "required",
    "message": "object has missing required properties ([\"b\"])",
    "required": ["a", "b"],
    "missing": ["b"]
  },
  {
    "level": "error",
    "schema": {
      "loadingURI": "file:/schema/object-array-schema.json#",
      "pointer": "/items/properties/a"
    },
    "instance": {
      "pointer": "/2/a"
    },
    "domain": "validation",
    "keyword": "minLength",
    "message": "string \"\" is too short (length: 0, required minimum: 1)",
    "value": "",
    "found": 0,
    "minLength": 1
  },
  {
    "level": "error",
    "schema": {
      "loadingURI": "file:/schema/object-array-schema.json#",
      "pointer": "/items/properties/a"
    },
    "instance": {
      "pointer": "/3/a"
    },
    "domain": "validation",
    "keyword": "minLength",
    "message": "string \"\" is too short (length: 0, required minimum: 1)",
    "value": "",
    "found": 0,
    "minLength": 1
  },
  {
    "level": "error",
    "schema": {
      "loadingURI": "file:/schema/object-array-schema.json#",
      "pointer": "/items/properties/b"
    },
    "instance": {
      "pointer": "/3/b"
    },
    "domain": "validation",
    "keyword": "minLength",
    "message": "string \"\" is too short (length: 0, required minimum: 1)",
    "value": "",
    "found": 0,
    "minLength": 1
  },
  {
    "level": "error",
    "schema": {
      "loadingURI": "file:/schema/object-array-schema.json#",
      "pointer": "/items"
    },
    "instance": {
      "pointer": "/4"
    },
    "domain": "validation",
    "keyword": "required",
    "message": "object has missing required properties ([\"a\"])",
    "required": ["a", "b"],
    "missing": ["a"]
  },
  {
    "level": "error",
    "schema": {
      "loadingURI": "file:/schema/object-array-schema.json#",
      "pointer": "/items/properties/b"
    },
    "instance": {
      "pointer": "/4/b"
    },
    "domain": "validation",
    "keyword": "minLength",
    "message": "string \"\" is too short (length: 0, required minimum: 1)",
    "value": "",
    "found": 0,
    "minLength": 1
  }
]
```

## Schema Redirections

Some JSON schemas might reference other schemas through a public URI. However, you might not want to
fetch those schemas from the internet, mainly for performance and security reasons.

The solution to that problem is to include all the main and referenced schemas in your application.
However, this solution generates a new problem: You need to make the original schema point to your
local schemas instead of the public ones.

To help with this problem, the module has the concept of schema redirects, which lets you replace an
external reference with a local one, without the need to modify the schema itself:

```xml
<flow name="process">
    <json:validate-schema schema="/schema/my-schema.json">
        <json:schema-redirects>
            <json:schema-redirect from="http://mule.org/schemas/fstab.json" to="schema/fstab.json"/>
        </json:schema-redirects>
    </json:validate-schema>
</flow>
```

The example above redirects the schema at
`[http://mule.org/schemas/fstab.json](http://mule.org/schemas/fstab.json)` with one shipped inside
your application with the path `schema/fstab.json`

## Additional Options

The validator contains additional options, such as whether to allow duplicate keys or not, how to
treat dereferencing, and so on.

For complete details, see [JSON Module Documentation Reference](https://docs.mulesoft.com/json-module/latest/json-reference).

## See Also

- [JSON Module Overview](https://docs.mulesoft.com/json-module/latest/)