JSON Folder

You use the elements in the JSON folder for the following:

  • Converting JSON content into a document (IData object)
  • Converting a document (IData object) into JSON content
  • Validating JSON content against a JSON schema

Data Type Mapping

The following table shows how JSON data types and JSON document types map to Integration Server data types during data conversion.

JSON Integration Server
object Document
string String
number (integer) Integer or Long Java wrapper. For more information about converting JSON integers, see the decodeIntegerAsLong input parameters in pub.json:jsonStreamToDocument and pub.json:jsonStringToDocument.
number (real) Float or Double Java wrapper. For more information about converting real numbers, see the decodeRealAsDouble input parameter in pub.json:jsonStreamToDocument and pub.json:jsonStringToDocument.

In JSON document type which is created from a JSON schema, if the data type is number, the JSON text will be converted to BigDecimal.

true/false Boolean Java wrapper
Array of JSON type Array of Integration Server type
  • If the JSON object contains a string array, Integration Server sets the corresponding field in the IS document type to String List.
  • If the JSON object contains a two-dimensional string array, Integration Server sets the corresponding field in the IS document type to String Table.
  • If the JSON object contains a array having different types of objects (for example, integer, string, etc.), Integration Server sets the corresponding field in the IS document type to Object List with Java wrapper type as UNKNOWN.
Note: The Flow type system in Integration Server does not support the following multi-dimensional arrays in JSON objects:
  • Two-dimensional arrays of data types other than string
  • Multi-dimensional arrays of three or more dimensions (three-dimensional, four-dimensional, etc.)

The JSON coder in Integration Server can create pipelines with arbitrarily deep arrays or various types and you can write Java services to access those arrays. The limitations above apply to Flow services and viewing the document in Designer.

For pub.json:jsonStringToDocument and pub.json:sonStreamToDocument, these kinds of arrays become an Object List of UNKOWN type. For IS document types created from a JSON object using Integration Server, these kinds of arrays become an Object with a Java wrapper type of UNKNOWN.

Array of null Object List
null null
All others String
Note: If an object has a toString() implementation, Integration Server uses that implementation.

If the object does not provide a toString() implementation, Integration Server uses Object.toString(). Object.toString() returns the class name and hexadecimal representation of the hash code of the object, such as "javax.namining.InitialContext@3ae6f00b".

Additional notes on data conversion:

  • If JSON text begins with an array at the root and the array is unnamed, when parsing the JSON text, Integration Server uses a fixed name of $rootArray for the array value. The $rootArray field appears in the output pipeline of the service converting the JSON text to a Document (IData). When creating a JSON response, if the pipeline contains $rootArray with an array as its value, Integration Server discards the $rootArray name and transforms the array value into a JSON array. The resulting JSON text will contain only an unnamed array.
  • If JSON text contains only a primitive type (string, number, boolean, or null) at root level, Integration Server uses a fixed name of $rootValue for the primitive value while converting it to IData.

    The following table identifies how JSON text with a primitive type is converted to an IData in Integration Server:

    JSON text Generated IData
    "just a simple string" 
    {    
$rootValue="just a simple string" 
}
    3.14159 
    { 
$rootValue=3.14159 
}
    true {$rootValue=true}
    null {$rootValue=null}
    null {}

    Empty IData (if decodeNullRootAsEmpty input parameter is set to true)

  • With regards to using Integration Server data types with JSON, Integration Server supports only those types that can be mapped to a JSON value as defined in https://tools.ietf.org/html/rfc7159#section-3. Integration Server can take any valid arbitrary JSON text and convert it to an IData. Integration Server must be able to convert the resulting IData to JSON text that is identical to the original text. If Integration Server cannot do that for an Integration Server data type, then Integration Server does not support the use of that data type with JSON. For example, com.wm.util.Table is not supported for JSON even though it is supported for XML. Integration Server embeds additional type information in XML when converting IData to XML. However, Integration Server cannot embed the additional type information in JSON because the additional type information is treated as JSON text. The resulting JSON text would not match the original JSON text.
  • An exception to the guideline that Integration Server must be able to convert the resulting IData to JSON text that is identical to the original text involves primitive JSON type null. If the JSON text is null and decodeNullRootAsEmpty is set to true in the service performing the conversion, JSON text of null will get converted to empty IData and an empty IData will get converted to {} JSON text.

Summary of Elements in This Folder

The following elements are available in this folder:

Element Package and Description
pub.json:closeArrayIterator WmPublic. Closes the iteration. The iterator object used in an iteration cannot be reused after this service runs.
pub.json:documentToJSONString WmPublic. Converts a document (IData object) to a JSON string.
pub.json:getArrayIterator WmPublic. Returns an iterator object to iterate over arrays in the input JSON stream.
pub.json:getNextBatch WmPublic. Gets the next batch of array elements by parsing arrays in the iterator object returned by the pub.json:getArrayIterator service.
pub.json:jsonStreamToDocument WmPublic. Converts content from the JSON content stream to a document (an IData object).
pub.json:jsonStringToDocument WmPublic. Converts a JSON string to a document (an IData object).
pub.json.schema:validate WmPublic. Validates JSON content against a JSON document type.

pub.json:closeArrayIterator

WmPublic. Closes the iteration. The iterator object used in an iteration cannot be reused after this service runs.

Input Parameters

iterator Object. The iterator object returned by the pub.json:getNextBatch service.

Output Parameters

None.

pub.json:documentToJSONString

WmPublic. Converts a document (IData object) to a JSON string.

Input Parameters

document Document. The document (IData object) to be converted to a JSON string.
encodeDateAs String. Optional. Specifies how java.util.Date instances in the document are encoded in the returned JSON. Set to one of the following:
  • long to encode java.utilData instances as timestamps, specifically the number of milliseconds since Jan 1, 1970 00:00:00. The dates are encoded as JSON numbers.
  • ISO8601 to encode java.utilData instances as strings in a standard ISO format of: YYYY-MM-DD'T'HH:mm:ss.sssZ. The dates are encoded JSON Strings.
  • Custom format in which dates are encoded as strings in the supplied pattern. The pattern must adhere to the date and time patterns as described in the java.text.SimpleDateFormat class in the Oracle Java API documentation. The dates are encoded as JSON strings.
  • null to use the dateEncoding setting already in effect for the HTTP client making the request, as follows:
    • If the HTTP client request includes jsonDateEncoding=long in the URL, then java.utilData instances as timestamps, specifically the number of milliseconds since Jan 1, 1970 00:00:00. The dates are JSON numbers.
    • If the HTTP client request includes jsonDateEncoding=ISO8601 in the URL, the java.utilData instances are encoded as strings in a standard ISO format of: YYYY-MM-DD'T'HH:mm:ss.sssZ. The dates are JSON Strings.
    • If the HTTP client request includes jsonDateEncoding= format in the URL, the java.utilData instances are encoded as strings in the supplied pattern. The pattern must adhere to the date and time patterns as described in the java.text.SimpleDateFormat class in the Oracle Java API documentation.
    • If the HTTP client request does not include the jsonDateEncoding query parameter in the URL, the service uses the value of the watt.server.json.encodeDateAs parameter. For more information about watt.server.json.encodeDataAs, see webMethods Integration Server Administrator’s Guide
jsonDocumentTypeName String. Optional. If specified, the transformation from Document (IData) to JSON string is based on the JSON document type. Any deviations from the provided JSON document might cause transformation errors.

When this parameter is provided, Integration Server ignores the encodeDateAs parameter and the watt.server.json.encodeDateAs server configuration parameter.

This parameter must have the fully qualified name of a JSON document type on Integration Server against which the JSON content is validated. This parameter must be in the format: <Folder Name>:<JSON Document Type Name>

For example: data:employeeData

prettyPrint String. Optional. Formats the jsonString output parameter for human readability by adding carriage returns and indentation to the JSON content. Set to:
  • true to format jsonString output variable for human readability.
  • false to leave the jsonString output variable in its unformatted state. The service will not add any additional carriage returns or indentation to the JSON content.
  • null to use the prettyPrint setting already in effect for the HTTP client making the request, as follows:
    • If the HTTP client request includes jsonPrettyPrint=true in the URI, JSON pretty printing is in effect.
    • If the HTTP client request includes jsonPrettyPrint=false in the URI, JSON pretty printing is not in effect.
    • If the HTTP client request does not include the jsonPrettyPrint parameter, the service uses the value of the watt.server.json.prettyPrint configuration parameter. For more information about watt.server.json.prettyPrint, see webMethods Integration Server Administrator’s Guide .
strict String. Optional. Valid values are true and false. The default value is false.
The values of strict and jsonDocumentTypeName parameters together determine how Integration Server parses and converts Document (IData) to JSON string in the following manner:
  • When strict is false and jsonDocumentTypeName is not specified, there is no change in the behavior.

  • When strict is false and jsonDocumentTypeName is specified, the transformation from Document (IData) to JSON string is loosely based on the JSON document type. For conversion rules, see Table 2: Conversion of IData to JSON String.

  • When strict is true and jsonDocumentTypeName is not specified, the service returns an exception.

  • When strict is true and jsonDocumentTypeName is specified, the transformation from Document (IData) to JSON string is strictly based on the JSON document type. The validation is performed first before the transformation, and any deviations lead to transformation errors. The encodeDateAs parameter and the watt.server.json.encodeDateAs server configuration parameter, if specified, are ignored.

Output Parameters

jsonString String. JSON string resulting from the conversion of document.

Usage Notes

To turn a document in a pipeline into a JSON response to send over HTTP, the application's service can:
  1. Use pub.json:documentToJSONString to turn a document (IData object) in the pipeline into a string of JSON content.
  2. Call pub.client:http to send the JSON string as an HTTP request.
  3. Set the Content-Type header field to application/json.

When creating a JSON text with pub.json:documentToJSONString, if the document input parameter contains a $rootArray key with an array as its value, Integration Server discards the $rootArray name and transforms the array value into a JSON array. The resulting JSON text will contain only an unnamed array. $rootArray and key/value pairs cannot both appear in the input document. $rootArray indicates that the generated JSON text should consist only of an unnamed array. Combining this with additional key/value pairs leads to unpredictable results.

The JSON standard requires that field names be enclosed in double quotes. However, you may need the service to produce unquoted field names if the generated JSON text will be processed by an older JavaScript interpreter. The watt.server.json.quoteFieldNames server configuration parameter determines whether the pub.json:documentToJSONString service encloses all generated JSON field names in double quotes. Set this parameter to true instruct the pub.json:documentToJSONString service to enclose field names in quotes in the output JSON text. Set this parameter to false to instruct the service to omit the double quotes around field names in the generated JSON text. The default is true.

Note: Use caution when setting watt.server.json.quoteFieldNames to false as this causes the pub.json:documentToJSONString service to generate non-standard JSON text. This can cause interoperability issues if the JSON text is sent to other organizations.

When strict=true, the validation of a JSON document against the JSON document type happens before transformation, and the validation exception, if any, contains the first error message, which is the result of the pub.json.schema:validate service execution. The validation errors from the pub.json.schema:validate service, if any, can be one or more in the service output. However, only the first error message is displayed in the pub.json:documentToJSONString service exception.

When you validate a JSON document against the JSON document type, the format property in the JSON document type is ignored during transformation. Therefore, the value passed is retained in the same format even after the successful transformation.

pub.json:getArrayIterator

WmPublic. Returns a batch iterator object.

Input Parameters

jsonStream Object. JSON content to be converted to a document (an IData object).
arrayPaths String List. The paths of the arrays to be parsed in the JSON input stream. Only the array elements from the paths mentioned in this parameter are considered even though the JSON stream might have more data. For example, to retrieve toppingA1 from the following JSON content, provide the array path as /topping/0/toppingA/0/toppingA1. 
"topping": [{ 
            "toppingA": [{ 
                    "toppingA1": ["None71", "Glazed82"] 
... 
                }]}]
Note:

This parameter must have only array paths. You must not enter individual array elements or other fields.

Array paths must follow the JSON pointer syntax.

decodeRealAsDouble String. Optional. Converts real numbers from jsonStream to either a Float or Double Java wrapper type. Set to:
  • true to convert real numbers to Double Java wrapper type. This is the default.
  • false to convert real numbers to Float Java wrapper type.
Note: The decodeRealAsDouble parameter overrides the value specified by the watt.server.json.decodeRealAsDouble server configuration parameter. If no value is supplied for decodeRealAsDouble, Integration Server uses the value set for watt.server.json.decodeRealAsDouble. For more information about watt.server.json.decodeRealAsDouble, see webMethods Integration Server Administrator’s Guide .
decodeIntegerAsLong String. Optional. Converts integers from jsonStream to either a Long or Integer Java wrapper type. Set to:
  • true to convert integers to Long Java wrapper types. This is the default.
  • false to convert integers to Integer Java wrapper types.
Note: The decodeIntegerAsLong parameter overrides the value specified by the watt.server.json.decodeIntegerAsLong server configuration parameter. If no value is supplied for decodeIntegerAsLong, Integration Server uses the value specified in the watt.server.json.decodeIntegerAsLong property. For more information about watt.server.json.decodeIntegerAsLong, see webMethods Integration Server Administrator’s Guide .
decodeRealAsString String. Optional. Converts real numbers in the jsonStream to String. Set to:
  • true to convert real numbers to String.
  • false to not convert real numbers to String. The real numbers are then converted to either Float or Double Java wrapper type depending on the value specified in decodeRealAsDouble. This is the default value.
Note: The decodeRealAsString parameter overrides the value specified by the watt.server.json.decodeRealAsString server configuration parameter. If no value is supplied for decodeRealAsString, Integration Server uses the value set in watt.server.json.decodeRealAsString. For more information about watt.server.json.decodeRealAsString, see webMethods Integration Server Administrator’s Guide .
unescapeSpecialChars String. Optional. Controls whether Integration Server unescapes the special characters '\n', '\r', '\t', '\b', '\f', '\\', '\"' while parsing JSON documents. Set to:
  • true to unescape these special characters (that is, '\n' will be replaced with new line, similarly other characters will also be replaced) in the output document. This is the default.
  • false to keep these characters as is in the output document.
Note: The unescapeSpecialChars parameter overrides the value specified by the watt.server.json.decode.unescapeSpecialChars server configuration parameter. If no value is supplied for unescapeSpecialChars, Integration Server uses the value specified in the watt.server.json.decode.unescapeSpecialChars parameter. For more information about watt.server.json.decode.unescapeSpecialChars, see webMethods Integration Server Administrator’s Guide .

Output Parameters

iterator Object. A batch iterator object that has the list of arrays to be parsed in the JSON input stream. This object is passed as input to the pub.json:getNextBatch service.

Usage Notes

None.

pub.json:getNextBatch

WmPublic. Gets the next batch of array elements by parsing the array paths in the iterator object returned by the pub.json:getArrayIterator service. This service returns the array elements in batches based on the batch size provided in the input. The batch size can vary across invocations of this service. A batch is a set of elements that can be retrieved from an array path at once, based on the batch size. To retrieve the remaining elements in the array path or elements from the next array path in the iterator, invoke the service in a loop until there are no more array paths to iterate.

Input Parameters

iterator Object. The iterator object returned by the pub.json:getArrayIterator service.
batchSize Object. Number of array elements that the service should retrieve in one batch.
Note: This value must be lesser or equal to the value of the watt.server.json.iterator.maxBatchSize server configuration property. Similarly, it must be greater or equal to the value of the watt.server.json.iterator.minBatchSize server configuration property. Otherwise, the service throws an error.

Output Parameters

batch Document. IData object that contains the following keys.
  Key Description
  arrayPath String. The path of the array elements retrieved in a batch. Since the service can iterate over multiple arrays, each batch contains the array path parsed in current iteration to help you identify the array to which the elements in the batch belong.
  documents Document List. If array elements in the batch are JSON objects, they are returned as documents.
  values Object List. If array elements in the batch are not JSON objects, they are returned as values.
iterationStatus Document. IData object that contains the following keys.
  hasNext String. Indicates whether there are more array elements in the iterator beyond this batch, which the service can retrieve. The value can be true or false.
  iteration String. Indicates the current iteration. It starts from 1. If the service runs N times to get all the array elements, then this value is N.
  numberOfElementsInBatch String. Indicates the number of elements in the current batch. This value is same as batchSize.

However, this value can be less than the batch size for the last batch. For example, if there are 7 elements in an array and the batch size is 5, then the last batch will have only 2 elements.

  totalElementsParsed String. Indicates the number of array elements parsed until the current iteration. For example, if the number of elements parsed in the first iteration is 10, second iteration is 20, and third iteration is 7, then in the third iteration, the value of this parameter is 37.

Usage Notes

The pub.json:getNextBatch service completes the retrieval of elements from one array in the iterator and starts retrieving from the next array that matches in the subsequent iteration. This is explained in the following example: Suppose you want the service to parse a JSON file with 2 arrays, for example, A and B with 6 and 2 elements each. Set the batchSize input parameter to 5 and invoke the service in a loop until the service returns the hasNext parameter as false. In the first batch of the output, the first 5 elements of the array A are returned and in the next batch, only the last element of the array A is returned, even though the batch size is 5. At this point, the hasNext parameter is true because array B is not parsed yet. In the next batch, the service returns both the elements of array B. Since there are no more elements left either in the array A or B, the hasNext parameter becomes false.

Guidelines
  • If two array paths overlap, the path that the service finds first in the input JSON stream is parsed and the other path is ignored. If you provide arrayPath[0] as /a/b and arrayPath[1] as /a/b/0/c to parse the following array, arrayPath[1] is ignored as the paths overlap and the first path retrieves all elements. 
    { 
    "a": { 
        "b": [{ 
            "f1": "v1", 
            "c": [1, 2, 3] 
        }] 
    } 
}
  • If an invalid array path is provided in the input, the pub.json:getNextBatch service does not return any result on parsing the array.
  • If the arrayPaths input parameter is not set, then the pub.json:getNextBatch service parses the input considering that the input stream has a single anonymous array at the root level.
  • If the arrayPaths input parameter is set, then it cannot contain null or empty elements.
  • If one or more array paths are invalid, then the pub.json:getArrayIterator service still creates an iterator object containing these paths. However, the pub.json:getNextBatch service ignores the invalid paths.

    If all the paths are invalid, the pub.json:getNextBatch service returns the documents and values parameters as null, the hasNext parameter as false, and all other output parameters as 0.

pub.json:jsonStreamToDocument

WmPublic. Converts content from the JSON content stream to a document (an IData object). This service loads the whole JSON data into memory and then converts to an IData object.

Input Parameters

jsonStream Object. JSON content in an input stream to convert to a document (an IData object).
decodeRealAsDouble String. Optional. Converts real numbers from jsonStream to either a Float or Double Java wrapper type. Set to:
  • true to convert real numbers to Double Java wrapper types. This is the default.
  • false to convert real numbers to Float Java wrapper types.
Note: The decodeRealAsDouble parameter overrides the value specified by the watt.server.json.decodeRealAsDouble server configuration parameter. If no value is supplied for decodeRealAsDouble, Integration Server uses the value set in watt.server.json.decodeRealAsDouble. For more information about watt.server.json.decodeRealAsDouble, see webMethods Integration Server Administrator’s Guide .
decodeRealAsString String. Optional. Converts real numbers in the jsonStream to String. Set to:
  • true to convert real numbers to String.
  • false to not convert real numbers to String. The real numbers are then converted to either Float or Double Java wrapper type depending on the value specified in decodeRealAsDouble. This is the default.
Note: The decodeRealAsString parameter overrides the value specified by the watt.server.json.decodeRealAsString server configuration parameter. If no value is supplied for decodeRealAsString, Integration Server uses the value set in watt.server.json.decodeRealAsString. For more information about watt.server.json.decodeRealAsString, see webMethods Integration Server Administrator’s Guide .
decodeIntegerAsLong String. Optional. Converts integers from jsonStream to either a Long or Integer Java wrapper type. Set to:
  • true to convert integers to Long Java wrapper types. This is the default.
  • false to convert integers to Integer Java wrapper types.
Note: The decodeIntegerAsLong parameter overrides the value specified by the watt.server.json.decodeIntegerAsLong server configuration parameter. If no value is supplied for decodeIntegerAsLong, Integration Server uses the value specified in the watt.server.json.decodeIntegerAsLong property. For more information about watt.server.json.decodeIntegerAsLong, see webMethods Integration Server Administrator’s Guide .
decodeNullRootAsEmpty String. Optional. Converts a null value that Integration Server retrieves from JSON content to either IData or empty IData. Set to:
  • true to convert the null value to empty IData. The subsequent encoding of empty IData creates a JSON text of “{}”. This JSON content is different from the original JSON content (null) as the original null value gets converted to JSON text of "{}".
  • false to convert the null value to IData. This is the default.
jsonDocumentTypeName String. Optional. If specified, the transformation from the JSON stream to Document (IData) is based on the JSON document type. Any deviations from the provided JSON document might cause transformation errors.
When this parameter is provided, Integration Server ignores the following parameters:
  • decodeRealAsDouble
  • decodeIntegerAsLong
  • decodeRealAsString
and the following server configuration parameters:
  • watt.server.json.decodeIntegerAsLong
  • watt.server.json.decodeRealAsDouble
  • watt.server.json.decodeRealAsString

This parameter must have the fully qualified name of a JSON document type on Integration Server against which the JSON content is validated. This parameter must be in the format: <Folder Name>:<JSON Document Type Name>

For example: data:employeeData

strict String. Optional. Valid values are true and false. The default value is false.
The values of strict and jsonDocumentTypeName parameters together determine how Integration Server parses and converts JSON stream to Document (IData) in the following manner:
  • When strict is false and jsonDocumentTypeName is not specified, there is no change in the behavior.
  • When strict is false and jsonDocumentTypeName is specified, the transformation from JSON stream to Document (IData) is loosely based on the JSON document type. For conversion rules, see Table 1: Conversion of JSON Payload to IData.

  • When strict is true and jsonDocumentTypeName is not specified, the service returns an exception.

  • When strict is true and jsonDocumentTypeName is specified, the transformation from JSON stream to Document (IData) is strictly based on the JSON document type. The validation is performed first before the transformation, and any deviations lead to transformation errors. The decodeRealAsDouble, decodeIntegerAsLong, and decodeRealAsString parameters and the server configuration parameters, if specified, are ignored.
unescapeSpecialChars String. Optional. Controls whether Integration Server unescapes the special characters '\n', '\r', '\t', '\b', '\f', '\\', '\"' while parsing JSON documents. Set to:
  • true to unescape these special characters (that is, '\n' will be replaced with new line, similarly other characters will also be replaced) in the output document. This is the default.
  • false to keep these characters as is in the output document.
Note: The unescapeSpecialChars parameter overrides the value specified by the watt.server.json.decode.unescapeSpecialChars server configuration parameter. If no value is supplied for unescapeSpecialChars, Integration Server uses the value specified in the watt.server.json.decode.unescapeSpecialChars parameter. For more information about watt.server.json.decode.unescapeSpecialChars, see webMethods Integration Server Administrator’s Guide .

Output Parameters

document Document. Document (IData object) resulting from the conversion of jsonStream.

Usage Notes

If watt.server.http.jsonFormat is set to stream, Integration Server places a jsonStream variable in the pipeline when it receives an HTTP request containing JSON content. You can then use pub.json:jsonStreamToDocument to parse jsonStream into pipeline variables. If watt.server.http.jsonFormat is set to parsed, which is the default, the JSON content handler parses the JSON content in the HTTP request automatically. In this case, the pub.json:jsonStreamToDocument does not need to be invoked. For more information about watt.server.http.jsonFormat, see webMethods Integration Server Administrator’s Guide .

A JSON text may contain only an unnamed array. When parsing such a JSON text with pub.json:jsonStreamToDocument, Integration Server uses a fixed name of $rootArray for the array value. The $rootArray field appears in the document output parameter.

The JSON standard requires that field names be enclosed in double quotes. However, when parsing legacy JavaScript as JSON text it may be helpful to allow unquoted field names as JavaScript does not require field names to be enclosed in double quotes. The server configuration parameter watt.server.json.allowUnquotedFieldNames specifies whether or not unquoted field names are allowed in JSON text passed to thepub.json:jsonStringToDocument and pub.json:jsonStreamToDocument services. If this parameter is set to true, the pub.json:jsonStringToDocument and pub.json:jsonStreamToDocument services allow unquoted field names in any supplied JSON text. If this parameter is set to false, the services throw a ServiceException when encountering unquoted field names. The default is false.

If decodeRealAsString is set to true and decodeRealAsDouble is either set to true or left blank, an error message is displayed.

SetdecodeRealAsString to true to prevent the conversion of real numbers to scientific notation.

When the jsonString input parameter containing duplicate keys is validated against the jsonDocumentTypeName with strict set totrue in the pub.json:jsonStringToDocument service, the transformation might fail even when the pub.json.schema:validate service successfully validates the same jsonString.

When strict=true, the validation of a JSON document against the JSON document type happens before transformation, and the validation exception, if any, contains the first error message, which is the result of the pub.json.schema:validate service execution. The validation errors from the pub.json.schema:validate service, if any, can be one or more in the service output. However, only the first error message is displayed in the pub.json:jsonStreamToDocument service exception.

When you validate a JSON document against the JSON document type, the format property in the JSON document type is ignored during transformation. Therefore, the value passed is retained in the same format even after the successful transformation.

Important: Since this service loads the whole JSON data into memory and then converts it to an IData object, it is not meant to process large JSON files (for example, 50GB or more). Large JSON files can be processed in fixed-size logical chunks using the pub.json:getArrayIterator, pub.json:getNextBatch and the pub.json:closeArrayIterator public services together.

pub.json:jsonStringToDocument

WmPublic. Converts a JSON string to a document (an IData object).

Input Parameters

jsonString String. JSON content in a string to convert to a document (IData object).
decodeRealAsDouble String. Optional. Converts real numbers from jsonString to either a Float or Double Java wrapper type. Set to:
  • true to convert real numbers to Double Java wrapper types. This is the default.
  • false to convert real numbers to Float Java wrapper types.
Note: The decodeRealAsDouble parameter overrides the value specified by the watt.server.json.decodeRealAsDouble server configuration parameter. If no value is supplied for decodeRealAsDouble, Integration Serveruses the value set in watt.server.json.decodeRealAsDouble. For more information about watt.server.json.decodeRealAsDouble, see webMethods Integration Server Administrator’s Guide .
decodeRealAsString String. Optional. Converts real numbers in the jsonStream to String. Set to:
  • true to convert real numbers to String.
  • false to not convert real numbers to String. The real numbers are then converted to either Float or Double Java wrapper type depending on the values specified in decodeRealAsDouble. This is the default.
Note: The decodeRealAsString parameter overrides the value specified by the watt.server.json.decodeRealAsString server configuration parameter. If no value is supplied for decodeRealAsString, Integration Server uses the value set in watt.server.json.decodeRealAsString. For more information about watt.server.json.decodeRealAsString, see webMethods Integration Server Administrator’s Guide .
decodeIntegerAsLong String. Optional. Converts integers from jsonString to either a Long or Integer Java wrapper type. Set to:
  • true to convert integers to Long Java wrapper types. This is the default.
  • false to convert integers to Integer Java wrapper types.
Note: The decodeRealAsDouble parameter overrides the value specified by the watt.server.json.decodeIntegerAsLong server configuration parameter. If no value is supplied for decodeIntegerAsLong, Integration Server uses the value specified in the watt.server.json.decodeIntegerAsLong property. For more information about watt.server.json.decodeIntegerAsLong, see webMethods Integration Server Administrator’s Guide .
decodeNullRootAsEmpty String. Optional. Converts a null value that Integration Server retrieves from JSON content to either IData or empty IData. Set to:
  • true to convert the null value to empty IData. The subsequent encoding of empty IData creates a JSON text of “{}”. This JSON content is different from the original JSON content (null) as the original null value gets converted to JSON text of "{}".
  • false to convert the null value to IData. This is the default.
jsonDocumentTypeName String. Optional. If specified, the transformation from JSON string to Document (IData) is based on the JSON document type. Any deviations from the provided JSON document might cause transformation errors.
When this parameter is provided, Integration Server ignores the following parameters:
  • decodeRealAsDouble
  • decodeIntegerAsLong
  • decodeRealAsString
and the following server configuration parameters:
  • watt.server.json.decodeIntegerAsLong
  • watt.server.json.decodeRealAsDouble
  • watt.server.json.decodeRealAsString

This parameter must have the fully qualified name of a JSON document type on Integration Server against which the JSON content is validated. This parameter must be in the format: <Folder Name>:<JSON Document Type Name>

For example: data:employeeData

strict String. Optional. Valid values are true and false. The default value is false.
The values of strict and jsonDocumentTypeName parameters together determine how Integration Server parses and converts JSON string to Document (IData) in the following manner:
  • When strict is false and jsonDocumentTypeName is not specified, there is no change in the behavior.
  • When strict is false and jsonDocumentTypeName is specified, the transformation from JSON string to Document (IData) is loosely based on the JSON document type. For conversion rules, see: Table 1: Conversion of JSON Payload to IData.

  • When strict is true and jsonDocumentTypeName is not specified, the service returns an exception.

  • When strict is true and jsonDocumentTypeName is specified, the transformation from JSON string to Document (IData) is strictly based on the JSON document type. The validation is performed first before the transformation, and any deviations lead to transformation errors. The decodeRealAsDouble, decodeIntegerAsLong, and decodeRealAsString parameters and the server configuration parameters, if specified, are ignored.
unescapeSpecialChars String. Optional. Controls whether Integration Server unescapes the special characters '\n', '\r', '\t', '\b', '\f', '\\', '\"' while parsing JSON documents. Set to:
  • true to unescape these special characters (that is, '\n' will be replaced with new line, similarly other characters will also be replaced) in the output document. This is the default.
  • false to keep these characters as is in the output document.
Note: The unescapeSpecialChars parameter overrides the value specified by the watt.server.json.decode.unescapeSpecialChars server configuration parameter. If no value is supplied for unescapeSpecialChars, Integration Server uses the value specified in the watt.server.json.decode.unescapeSpecialChars parameter. For more information about watt.server.json.decode.unescapeSpecialChars, see webMethods Integration Server Administrator’s Guide .

Output Parameters

document Document. Document (IData object) resulting from the conversion of jsonString.

Usage Notes

A JSON text may contain only an unnamed array. When parsing such a JSON text with pub.json:jsonStringToDocument, Integration Server uses a fixed name of $rootArray for the array value. The $rootArray field appears in the document output parameter.

The JSON standard requires that field names be enclosed in double quotes. However, when parsing legacy JavaScript as JSON text it may be helpful to allow unquoted field names as JavaScript does not require field names to be enclosed in double quotes. The server configuration parameter watt.server.json.allowUnquotedFieldNames specifies whether or not unquoted field names are allowed in JSON text passed to thepub.json:jsonStringToDocument and pub.json:jsonStreamToDocument services. If this parameter is set to true, the pub.json:jsonStringToDocument and pub.json:jsonStreamToDocument services allow unquoted field names in any supplied JSON text. If this parameter is set to false, the services throw a ServiceException when encountering unquoted field names. The default is false.

If decodeRealAsString is set to true and decodeRealAsDouble is either set to true or left blank, an error message is displayed.

Set decodeRealAsString to true to prevent the conversion of real numbers to scientific notation.

When the jsonString input parameter containing duplicate keys is validated against the jsonDocumentTypeName with strict set to true in the pub.json:jsonStringToDocument service, the transformation might fail even when the pub.json.schema:validate service successfully validates the same jsonString.

When strict=true, the validation of a JSON document against the JSON document type happens before transformation, and the validation exception, if any, contains the first error message, which is the result of the pub.json.schema:validate service execution. The validation errors from the pub.json.schema:validate service, if any, can be one or more in the service output. However, only the first error message is displayed in the pub.json:jsonStringToDocument service exception.

When you validate a JSON document against the JSON document type, the format property in the JSON document type is ignored during transformation. Therefore, the value passed is retained in the same format even after the successful transformation.

pub.json.schema:validate

WmPublic. Validates JSON content against a JSON document type.

Input Parameters

jsonString String. Optional. JSON content for validation in a String. If you specify the value of this parameter, you need not specify jsonStream or jsonDocument.
jsonStream java.io.InputStream. Optional. JSON content for validation in an input stream. If you specify the value of this parameter, you need not specify jsonString or jsonDocument.
jsonDocument Document. Optional. JSON content for validation in a document (IData object). If you specify the value of this parameter, you need not specify jsonString or jsonStream.
streamEncoding String. Optional. Character encoding that applies to jsonStream. The default is UTF-8.
conformsTo String Fully qualified name of a JSON document type on Integration Server against which the JSON content will be validated.

Output Parameters

isValid String. Flag that indicates whether or not validation was successful. A value of:
  • true indicates that validation was successful.
  • false indicates that validation was unsuccessful.
errors Document List. Conditional. Returned only when errors are encountered during validation.

Each document contains the following information:

  Key Description
  code String Error code (for example, JSV-001).
  message String Error message (for example, JSON schema validation failed).
  path String Location of the error.

Usage Notes

The JSON standard requires that field names be enclosed in double quotes. The pub.json.schema:validate service accepts input JSON content according to the JSON standard and treats field names not enclosed in double quotes (including unquoted field names) as invalid.

If the provided JSON input is invalid, then pub.json.schema:validate throws a ServiceException.

Specify only one of jsonString, jsonStream, or jsonDocument. If you specify more than one of these parameters, then pub.json.schema:validate considers only the first of the specified values for validation in the following order: jsonString, jsonStream, jsonDocument.

If you do not specify any JSON content for validation or the JSON schema file, then pub.json.schema:validate throws a ServiceException.

Table1: Conversion of JSON Payload to IData

Table 2: Conversion of IData to JSON Payload