Creating parse settings

A parse settings specifies the constraints of the input document that a parse action accepts. A document is rejected when a defined value exceeds a specified limit.

About this task

By default, the document type is detected and the parsing is based on the detected document type. Instead of detecting the document type, you can define settings to parse the payload based on document type. The supported document types are binary, XML, JSON, and GraphQL.

Parse settings are used when you configure the following objects.
  • A parse processing action
  • A parse assembly action
  • An API collection
Note: Only assembly actions support the GraphQL document type.
The checks that apply when you create a type-specific parse settings differ. The following list states the checks that apply for each supported document type.
Binary
For a binary large object (BLOB) document, the following checks apply.
  • Document size
XML
For an XML document, the following checks apply.
  • Document size
  • Nesting depth
  • Width
  • Name length
  • Value length
  • Unique names
  • Unique prefixes
  • Unique namespaces
JSON
For a JSON document, the following checks apply.
  • Document size
  • Nesting depth
  • Width
  • Name length
  • Value length
  • Number length
  • Unique names
  • Entire document in valid UTF-8 encoding
GraphQL
For a GraphQL document, the following checks apply.
  • Document size
  • Nesting depth
  • Width
  • Name length
  • Value length
The parsing for GraphQL happens 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
Query variables in the request can be sent as a JSON string in a variables query parameter. When the query contains several named operations, an operationName query parameter is needed to determine which operation to run. The JSON object is in the following format.
{
  "query": "query MyData ($idVar: Int!) { user (id: $idVar) { name }}",
  "operationName": "MyData",
  "variables": {"idVar": 123}
}
When a GraphQL query is parsed, it is recognized as one of the following types.
Standard introspection
A query that contains only introspection fields that are part of the GraphQL introspection system, such as __schema and __type.
Custom introspection
A query that contains introspection fields and one or more nonintrospection fields.
No introspection
A query that does not contain introspection fields.
Through the URL query of a GET request
The URL is in the following format.
http://myapi/graphql?query={me{name}}

Procedure

  1. In the search field, enter parse.
  2. From the search results, click Parse settings.
  3. Click Add or New.
  4. Define the basic properties: Name, administrative state, and descriptive summary.

Define common settings.

  1. From the Document type list, select the type of document for the parse action.
  2. Optional: In the Max document size field, specify the maximum document size in bytes.
    Enter a value in the range 0 - 5368709121. The default value is 4194304. A value of 0 indicates an unlimited. When 0, the action result does not return the document size.
  3. Optional: In the Max nesting depth field, specify the maximum nesting depth in a document.
    • For XML, the maximum level of element depth.
    • For JSON, 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, the maximum level of nested selection sets.

    Enter a value in the range 0 - 4096. The default value is 512. 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 action result does not return the nesting depth.

  4. Optional: In the Max width field, specify the maximum width of document payload.
    • For XML, the maximum number of attributes for an element or the maximum number of child elements for an element.
    • For JSON, the maximum number of properties on a JSON object or the maximum number of JSON items in a JSON array.
    • For GraphQL, the maximum number of selections in a selection set.

    Enter a value in the range 0 - 65535. The default value is 4096. A value of 0 indicates unlimited. When 0, the action result does not return the width.

  5. Optional: In the Max name length field, specify the maximum name length in bytes in a document.
    The length includes any white space that is contained between tags in XML or quotation marks in JSON.
    • For XML, the length of the name portion of a tag.
    • For JSON, the length of the label portion of the JSON label-value pair.
    • For GraphQL, the maximum length of the identifiers, which includes field names and directive names.

    Enter a value in the range 0 - 8192. The default value is 256. 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 action result does not return the name length of a document.

  6. Optional: In the Max value length field, specify the maximum value length in bytes in a document.
    The length includes any white space that is between tags in XML or quotation marks in JSON.
    • For XML, the length of an attribute or the length of a text value.
    • For JSON and GraphQL, the length of a string value.

    Enter a value in the range 0 - 5368709121. The default value is 8192. A value of 0 indicates unlimited. When 0, the action result does not return the value length.

  7. Optional: In the Max unique names field, specify the maximum number of unique names in a document.
    • For XML, the number is for unique XML local names.
    • For JSON, the number is for unique JSON labels.

    Enter a value in the range 0 - 1048575. The default value is 1024. A value of 0 indicates unlimited. When 0, the action result does not return the number of unique names.

Define settings specific to XML messages.

  1. Optional: In the Max unique prefixes field, specify the maximum number of unique XML namespace prefixes.
    This limit counts multiple prefixes for the same namespace, but does not count multiple namespaces in different parts of the input document under a single prefix. Enter a value in the range 0 - 262143. The default value is 1024. A value of 0 indicates unlimited. When 0, the action result does not return the number of unique prefixes.
  2. Optional: In the Max unique namespaces field, specify the maximum number of unique XML namespace URIs.
    This limit counts all XML namespaces, regardless of how many prefixes are used to declare them. Enter a value in the range 0 - 65535. The default value is 1024. A value of 0 indicates unlimited. When 0, the action result does not return the number of unique namespaces.

Define settings specific to JSON messages.

  1. Optional: In the Max number length field, specify the maximum number length in 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. The default value is 128. A document is rejected when the number length in the document exceeds the maximum length. A value of 0 indicates unlimited. When 0, the action result does not return the number length.
  2. Optional: Set the Strict UTF-8 encoding property to specify whether to enforce strict UTF-8 encoding throughout the entire document. By default, only the first few byes are checked.
    • When enabled, the entire document is checked for valid UTF-8 encoding.
    • When not enabled, only the first few bytes are checked for proper encoding. The rest of the document is assumed to be in the same encoding.
  3. Click Apply to save the changes to the running configuration.
  4. Click Save Configuration or Save changes to save the changes to the persisted configuration.