JSON Content Parser (proto)

This extension has the qualified name envoy.content_parsers.json

Note

This extension is functional but has not had substantial production burn time, use only with this caveat.

This extension is intended to be robust against untrusted downstream traffic. It assumes that the upstream is trusted.

Tip

This extension extends and can be used with the following extension category:

envoy.content_parsers

This extension must be configured with one of the following type URLs:

type.googleapis.com/envoy.extensions.content_parsers.json.v3.JsonContentParser

Warning

This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the threat model, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points.

Parses JSON content and extracts values using JSON path selectors. This parser operates on raw JSON content strings provided by the caller.

extensions.content_parsers.json.v3.JsonContentParser

[extensions.content_parsers.json.v3.JsonContentParser proto]

Configuration for the JSON content parser.

{
  "rules": []
}

rules: (repeated extensions.content_parsers.json.v3.JsonContentParser.RuleConfig, REQUIRED) The rules to apply for extracting values from JSON content. Rules are evaluated in order for each content item provided. At least one rule must be specified.

extensions.content_parsers.json.v3.JsonContentParser.RuleConfig

[extensions.content_parsers.json.v3.JsonContentParser.RuleConfig proto]

Configuration for a single rule with its processing behavior.

{
  "rule": {...},
  "stop_processing_after_matches": ...
}

rule: (extensions.filters.http.json_to_metadata.v3.JsonToMetadata.Rule, REQUIRED) The json-to-metadata rule to apply for extracting values from JSON content. See json_to_metadata rule for available configuration options including selectors, on_present, on_missing, on_error actions.

stop_processing_after_matches

(uint32) Controls how many times this rule should successfully match before stopping evaluation of this rule for subsequent content items.

If set to 0 (default): This rule is evaluated against all content items provided. Later matches may overwrite earlier values (unless preserve_existing_metadata_value is set in the rule), effectively extracting the LAST occurrence.
If set to 1: Stop evaluating this rule after the first successful match. This is useful for extracting values that appear early in the stream to avoid unnecessary processing of subsequent content.
If set to N > 1: Reserved for future use (e.g., aggregating multiple values). Values > 1 are currently rejected to prevent behavioral changes when this feature is implemented.

Example use cases:

Extract model name from early content: stop_processing_after_matches: 1 (Stops checking this rule after first match, doesn’t process remaining content for this rule)
Extract token usage from final content: stop_processing_after_matches: 0 (Processes all content items, extracts value from the last one that contains it)