Crate jmespath_extensions 

JMESPath Extensions

A comprehensive collection of 150+ extension functions for JMESPath queries.

Non-Standard Extension Warning

These functions are NOT part of the JMESPath specification.

Queries using these extension functions will NOT work in other JMESPath implementations (Python, JavaScript, Go, etc.). If you need portable queries, use only the 26 standard JMESPath built-in functions:

abs, avg, ceil, contains, ends_with, floor, join, keys, length, map, max, max_by, merge, min, min_by, not_null, reverse, sort, sort_by, starts_with, sum, to_array, to_number, to_string, type, values

These extensions are useful when:

• You control both the query author and the runtime environment
• You need functionality beyond standard JMESPath
• Cross-implementation compatibility is not required

Quick Start

use jmespath::{Runtime, Variable};
use jmespath_extensions::register_all;

// Create a runtime and register all extension functions
let mut runtime = Runtime::new();
runtime.register_builtin_functions();
register_all(&mut runtime);

// Use string functions
let expr = runtime.compile("upper(@)").unwrap();
let data = Variable::String("hello".to_string());
let result = expr.search(&data).unwrap();
assert_eq!(result.as_string().unwrap(), "HELLO");

Working with JSON Data

Most real-world usage involves querying JSON data:

use jmespath::{Runtime, Variable};
use jmespath_extensions::register_all;

let mut runtime = Runtime::new();
runtime.register_builtin_functions();
register_all(&mut runtime);

// Parse JSON data
let json = r#"{
    "users": [
        {"name": "alice", "email": "ALICE@EXAMPLE.COM"},
        {"name": "bob", "email": "BOB@EXAMPLE.COM"}
    ]
}"#;
let data = Variable::from_json(json).unwrap();

// Query with extension functions
let expr = runtime.compile("users[*].{name: upper(name), email: lower(email)}").unwrap();
let result = expr.search(&data).unwrap();

// Result: [{"name": "ALICE", "email": "alice@example.com"}, {"name": "BOB", "email": "bob@example.com"}]

Feature Flags

This crate uses feature flags to control which functions are included. This allows you to minimize dependencies and binary size.

Feature	Dependencies	Description
full (default)	all	All functions
core	none	String, array, object, math, type, utility, path
string	none	String manipulation
array	none	Array operations
object	none	Object utilities
math	none	Mathematical operations
type	none	Type conversion and checking
utility	none	Utility functions
path	none	Path manipulation
validation	none	Validation functions
hash	md-5, sha1, sha2, crc32fast	Hash functions
encoding	base64, hex	Encoding functions
url	url	URL functions
regex	regex	Regex functions
uuid	uuid	UUID generation
rand	rand	Random functions
datetime	chrono	Date/time functions
fuzzy	strsim	Fuzzy matching functions
expression	none	Expression-based functions
phonetic	rphonetic	Phonetic encoding functions
geo	geoutils	Geospatial functions
semver	semver	Semantic versioning
network	ipnetwork	Network/IP functions
ids	nanoid, ulid	ID generation
text	none	Text analysis
duration	none	Duration parsing
color	none	Color manipulation
computing	none	Computing utilities

Using Specific Features

# Only include string and array functions (no external dependencies)
[dependencies]
jmespath_extensions = { version = "0.1", default-features = false, features = ["string", "array"] }

# Include core functions plus regex
[dependencies]
jmespath_extensions = { version = "0.1", default-features = false, features = ["core", "regex"] }

Module Overview

See each module’s documentation for detailed function reference with examples:

• string - String manipulation (upper, lower, split, replace, camel_case, etc.)
• array - Array operations (first, last, unique, chunk, zip, range, etc.)
• object - Object utilities (items, pick, omit, deep_merge, etc.)
• math - Math operations (round, sqrt, pow, median, sin, cos, etc.)
• type_conv - Type functions (type_of, is_string, is_empty, to_number, etc.)
• utility - Utilities (default, if, coalesce, json_encode, etc.)
• datetime - Date/time (now, now_millis, parse_date, format_date, date_add, date_diff)
• fuzzy - Fuzzy matching (levenshtein, jaro_winkler, sorensen_dice, etc.)
• expression - Expression functions (map_expr, filter_expr, any_expr, all_expr, find_expr, sort_by_expr)
• path - Path functions (path_basename, path_dirname, path_ext, path_join)
• validation - Validation (is_email, is_url, is_uuid, is_ipv4, is_ipv6)
• hash - Hashing (md5, sha1, sha256, crc32)
• encoding - Encoding (base64_encode, base64_decode, hex_encode, hex_decode)
• url_fns - URL functions (url_encode, url_decode, url_parse)
• regex_fns - Regex (regex_match, regex_extract, regex_replace)
• random - Random (random, shuffle, sample, uuid)
• phonetic - Phonetic encoding (soundex, metaphone, double_metaphone, nysiis, sounds_like)
• geo - Geospatial (haversine, haversine_km, haversine_mi, bearing)
• semver_fns - Semantic versioning (semver_parse, semver_compare, semver_matches, is_semver)
• network - Network/IP (ip_to_int, int_to_ip, cidr_contains, cidr_network, is_private_ip)
• ids - ID generation (nanoid, ulid, ulid_timestamp)
• text - Text analysis (word_count, char_count, reading_time, word_frequencies)
• duration - Duration parsing (parse_duration, format_duration)
• color - Color manipulation (hex_to_rgb, rgb_to_hex, lighten, darken, color_mix)
• computing - Computing utilities (parse_bytes, format_bytes, bit_and, bit_or, bit_xor)

Error Handling

Extension functions follow JMESPath conventions:

• Type errors return an error (e.g., passing a number to upper)
• Invalid operations return null (e.g., index_at with out-of-bounds index)

use jmespath::{Runtime, Variable};
use jmespath_extensions::register_all;

let mut runtime = Runtime::new();
runtime.register_builtin_functions();
register_all(&mut runtime);

// Type error - upper expects a string
let expr = runtime.compile("upper(@)").unwrap();
let data = Variable::Number(serde_json::Number::from(42));
assert!(expr.search(&data).is_err());

// Out of bounds - returns null (requires "array" feature)
let expr = runtime.compile("index_at(@, `10`)").unwrap();
let data = Variable::from_json("[1, 2, 3]").unwrap();
let result = expr.search(&data).unwrap();
assert!(result.is_null());

Modules

array

Array manipulation functions.

color

Color manipulation functions.

common

Common types and utilities for JMESPath extension functions.

computing

Computing utility functions.

datetime

Date/time functions for JMESPath.

duration

Duration parsing and formatting functions.

encoding

Encoding functions.

expression

Expression-based functions for JMESPath.

fuzzy

Fuzzy string matching functions for JMESPath.

geo

Geospatial functions for JMESPath.

hash

Hash and checksum functions.

ids

ID generation functions for JMESPath.

math

Math and statistics functions.

network

Network/IP functions for JMESPath.

object

Object manipulation functions.

path

File path manipulation functions.

phonetic

Phonetic encoding functions for JMESPath.

random

Random and UUID generation functions.

regex_fns

Regular expression functions.

semver_fns

Semantic versioning functions for JMESPath.

string

String manipulation functions.

text

Text analysis functions for JMESPath.

type_conv

Type conversion and checking functions.

url_fns

URL encoding and parsing functions.

utility

Utility and conditional functions.

validation

Validation functions.

Macros

define_function

Helper macro for defining JMESPath custom functions.

Structs

Context

Context object used for error reporting.

JmespathError

JMESPath error.

Runtime

Compiles JMESPath expressions.

Signature

Represents a function’s signature.

Enums

ArgumentType

Function argument types used when validating.

ErrorReason

Error context to provide specific details about an error.

Variable

JMESPath variable.

Traits

Function

Represents a JMESPath function.

Functions

register_all

Register all available extension functions with a JMESPath runtime.

Type Aliases

Rcvar

Rc reference counted JMESPath Variable.