Parse

Use the Parse policy to control the parsing of an input document. When the input document is a JSON string, the string is parsed instead of copied over.

Table 1. Table showing which gateways support this policy, and the corresponding policy version
Gateway Policy version
DataPower® API Gateway 2.0.0

2.1.0 (DataPower API Gateway Version 10.0.1.4 or later)

This topic describes how to configure the policy in the assembly user interface; for details on how to configure the policy in your OpenAPI source, see parse.

About Parse

With the parse policy, you can retrieve parse settings by using the following methods in increasing order of precedence:
  1. Specify a valid parse settings configuration from which to retrieve its properties as the default parse settings.
    Note: If you change the default name, you must separately configure a corresponding ParseSettings object on the DataPower API Gateway.
  2. Specify a literal string as serialized XML or JSON properties as parse settings. These properties take precedence over any existing default properties. The literal string must be XML or JSON formatted.
    • The XML format is "<ParseSettings><propertyName>propertyValue</propertyName></ParseSettings>".
    • The JSON format is "{ \"ParseSettings\" : { \"propertyName\" : propertyValue } }".
  3. A URL that represents a named context from which to retrieve the serialized XML or JSON properties as parse settings. These properties take precedence over any existing literal or default properties.

Properties

The following table lists the policy properties, indicates whether a property is required, specifies the valid and default values for input, and specifies the data type of the values.

Table 2. Parse policy properties
Property label Required Description Data type
Title No The title of the policy.

The default value is parse.

 string
Description No A description of the policy. string
Use Content Type No If this setting is enabled and the parse setting is configured to detect the document type, the parse operation uses the Content-Type specified in the request headers.

If this setting is enabled and the document type in the parse setting is configured for either JSON or XML, the parse operation uses the Content-Type specified in the request headers and fails if the Content-Type in the request headers does not match the parse setting.

Enabling this setting is applicable only when the expected Content-Type is either JSON or XML.

If this setting is not enabled, the parse operation uses either the document type that is specified in the parse setting, or the detected document type if the parse setting is configured to detect the document type.

The check box is cleared by default.

 boolean
Parse settings object reference No An existing valid object from which to retrieve default property values for the dynamic object. string
Document type No The type of document to parse. Select one of the following options:
  • Detect: the document type is detected and the payload is parsed accordingly. This type is the default option.
  • JSON: the payload is parsed as JSON.
  • XML: the payload is parsed as XML.
  • Graphql: parsing is performed in one of the following ways:
    • As GraphQL in the body of a POST request. The GraphQL is in the following format:
      {
  me {
    name
  }
}
    • As a JSON string in the body of a POST request that contains a GraphQL query. The JSON object is in the following format:
      {
  "query": "query MyData ($idVar: Int!) { user (id: $idVar) { name }}",
  "operationName": "MyData",
  "variables": {"idVar": 123}
}
    • Through the URL query of a GET request. The URL is in the following format:
      https://myapi/graphql?query={me{name}}
      The following example includes the variables and operationName properties, with URL encoding (line-breaks are for table formatting only, your value will not include line-breaks):
      https://hostname/basepath/graphql?query=query%20fetchAccounts
%20($limit:%20Int)%20{accounts(limit:%20$limit)%20{name{first,last}}}
&variables={"limit":100}&operationName=fetchAccounts

Query variables in a GET request can be sent as a JSON string in a query parameter called variables. If the query contains several named operations, an operationName query parameter is required to determine which operation is to be executed.

 string
Maximum document size No Optionally, the maximum document size in bytes of a JSON, XML, or GraphQL input document that the parse operation accepts. This setting provides threat protection by enforcing the maximum document size. Enter a value in the range 0 - 5368709121. A document is rejected when its size exceeds the maximum size. A value of 0 indicates an unlimited document size. When set to 0, the operation result does not return the document size.

The default value is 4194304.

 integer
Maximum nesting depth No Optionally, the maximum nesting depth of an XML, JSON, or GraphQL message that the parse operation accepts. This setting provides threat protection by enforcing limits in the message.
  • When XML, it is the maximum level of element depth.
  • When JSON, it is the maximum level of nested label-value pairs, the maximum number of nested arrays, or the maximum number of combination of label-value pairs and arrays.
  • When GraphQL, it is the maximum level of nested selection sets.

Enter a value in the range 0 - 4096. A document is rejected when its nesting depth exceeds the maximum depth. A value of 0 indicates unlimited nesting depth. When set to 0, the operation result does not return the nesting depth.

The default value is 512.

 integer
Maximum width No Optionally, the maximum width of the payload that the parse operation accepts.
  • When the input document is XML, this property specifies the maximum number of attributes for an element or the maximum number of child elements for an element.
  • When the input document is JSON, this property specifies the maximum number of properties on a JSON object or the maximum number of JSON items in a JSON array.
  • When the input document is GraphQL, this property specifies the maximum number of selections in a selection set.

Enter a value in the range 0 - 65535. The document is rejected when its width exceeds the maximum width. A value of 0 indicates unlimited width. When set to 0, the operation result does not return the width of the document.

The default value is 4096.

 integer
Maximum name length No Optionally, the maximum name length in bytes in a document that the parse operation accepts.
  • For XML, it is the length of the name portion of a tag.
  • For JSON, it is the length of the label portion of the JSON label-value pair.
  • For GraphQL, it is the maximum length of the identifiers, including field names and directive names.

The length includes any white space that is contained between tags in XML or quotation marks in JSON. Enter a value in the range 0 - 8192. A document is rejected when its name length exceeds the maximum length. A value of 0 indicates unlimited name length. When set to 0, the operation result does not return the name length of a document.

The default value is 256.

 integer
Maximum value length No Optionally, the maximum value length in bytes in a document that the parse operation accepts.
  • For XML, it is the length of an attribute or the length of a text value.
  • For JSON and GraphQL, it is the length of a string value.

The length includes any white space that is contained between tags in XML or quotation marks in JSON. Enter a value in the range 0 - 5368709121. A document is rejected when its value length exceeds the maximum length. A value of 0 indicates unlimited value length. When set to 0, the operation result does not return the value length of a document.

The default value is 8192.

 integer
Maximum number of unique names No Optionally, the maximum number of unique names in a JSON or XML document that the parse operation accepts.
  • For XML, it is the number of unique XML local names.
  • For JSON, it is the number of unique JSON labels.

Enter a value in the range 0 - 1048575. A document is rejected when the number of unique names in the document exceeds the maximum number. A value of 0 indicates an unlimited number of unique names. When set to 0, the operation result does not return the number of unique names in a document.

The default value is 1024.

 integer
Maximum number of unique prefixes No Optionally, the maximum number of unique XML namespace prefixes in a document that the parse operation accepts. This limit counts multiple prefixes defined for the same namespace, but does not count multiple namespaces defined in different parts of the input document under a single prefix. Enter a value in the range 0 - 262143. A document is rejected when the number of unique prefixes in the document exceeds the maximum number. A value of 0 indicates an unlimited number of unique prefixes. When set to 0, the operation result does not return the number of unique prefixes in a document.

The default value is 1024.

 integer
Maximum number of unique namespaces No Optionally, the maximum number of unique XML namespace URIs that the parse operation accepts. This limit counts all XML namespaces, regardless of how many prefixes are used to declare them. Enter a value in the range 0 - 65535. A document is rejected when the number of unique namespaces in the document exceeds the maximum number. A value of 0 indicates an unlimited number of unique namespaces. When set to 0, the operation result does not return the number of unique namespaces in a document.

The default value is 1024.

 integer
Maximum number length No Optionally, the maximum number of bytes in the value portion of a JSON label-value pair when the value is a number. The number must be a contiguous string of bytes that contain no white space. The number can include a minus sign and a positive or negative exponent. Enter a value in the range 0 - 256. A document is rejected when the number length in the document exceeds the maximum length. A value of 0 indicates unlimited number length. When set to 0, the operation result does not return the number length in a document.

The default value is 128.

 integer
Parse settings literal configuration No A literal string as serialized XML or JSON properties that are merged into the dynamic object. These properties take preference over any existing default properties. string
Parse settings URL reference No A URL that represents a named context from which to retrieve the serialized XML or JSON properties that are merged into the dynamic object. These properties take preference over any existing literal or default properties. string
Message for parsing No The name of a variable in the API context. The content of the body field of the variable is the input to the policy. The default variable name is message. string
Message for resulting parsed data No The name of a variable in the API context. The content of the body field of the variable is the output of the parse operation. The parse metrics of the parsed document can be stored in a different part of the message. The default variable name is the same as the input name, so by default the input message is overwritten by the output message. string

Use the YAML source to set the following option.

Property Required Description Data type
strict-utf8-encoding No For JSON documents, whether to enforce strict UTF-8 encoding throughout the entire document.
  • When on, the entire document is checked for valid UTF-8 encoding.
  • When off, only the first few bytes are checked for proper encoding. The rest of the document is assumed to be in the same encoding.

The default value is off.

 boolean
For examples, see parse.