Creating parse settings

Parse settings specify 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

Tip: The equivalent entry point in the CLI is the global parse-settings command.

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.

An API collection
A GatewayScript policy in an assembly
A parse policy in an assembly
A map policy in an assembly
An XSLT policy in an assembly
A parse action in a processing policy

Note: Only policies in the assembly 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.

GraphQL in the body of a POST request

The GraphQL is in the following format.

{
  me {
    name
  }
}

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, a 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.

The URL query of a GET request

The URL is in the following format.

http://myapi/graphql?query={me{name}}

Procedure

In the search field, enter parse.
From the search results, click Parse settings.
Click Add.
Define the basic properties - Name, administrative state, and comments.

Define common settings.

From the Document type list, select the type of document for the parse action.
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.
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.
Optional: In the Max width field, specify the maximum width of the 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.
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.
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.
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.

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

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 without 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.
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.
Click Apply to save changes to the running configuration.
Click Save to save changes to the persisted configuration.