JMESPath evaluation #2878

robin-aws · 2025-12-05T23:19:17Z

Background

What do these changes do?
- Adds the ability to evaluate JmespathExpressions
  - Defines a JmespathRuntime<T> interface to provide the necessary basic operations on JSON values at runtime.
  - The actual Evaluator is largely ported over from smithy-java's JMESPathDocumentQuery, but also taking some inspiration from jmespath-java, which also has a generic interface for adapting any existing JSON value representation.
- Adds JmespathRuntime<T> implementations for both LiteralExpression and Node.
- Adds a separate smithy-jmespath-tests module with the compliance tests from https://github.com/jmespath/jmespath.test, and instantiates them for both runtime implementations.
Why are they important?
- The existing smithy-java evaluator only works on its own Document type, and evaluating expressions on generated types such as SerializableStruct subtypes currently requires first converting to a Document, which is slow. I've also written up implementations of JmespathRuntime for Document and generated types: see smithy-java link below.
- JMESPath expressions are very easy to get wrong. The existing type checker/linter helps catch egregious errors but is far from complete. Having an interpreter opens the door to features where models can provide examples/tests of their expressions, possibly using the pending @shapeExamples trait (Add new shapeExamples trait that communicates and enforces allowed and disallowed values #2851)

Testing

How did you test these changes?
- Mainly existing regression tests and the new smithy-jmespath-tests module.

Links

Use Smithy's JMESPath evaluator smithy-java#967

Note for reviewers: I'm not fully satisfied with how I've arranged the code into packages. I want to minimize how much API is exposed publicly, but didn't want to add all the new types into the base package. At the same time I don't want to expose the executable version of the Function interface publicly yet - I want to support custom functions in the future, but I'm not yet sure the current definition is optimal for that.

Edit: I dumped all of the Function-related types into the evaluation package and made them package-private. This can be revisited in a future change to support custom functions.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

# Conflicts: # VERSION

github-actions · 2025-12-05T23:19:37Z

This pull request does not contain a staged changelog entry. To create one, use the ./.changes/new-change command. For example:

./.changes/new-change --pull-requests "#2878" --type feature --description "Smithy jmespath evaluator"

Make sure that the description is appropriate for a changelog entry and that the proper feature type is used. See ./.changes/README or run ./.changes/new-change -h for more information.

github-actions · 2025-12-06T16:47:18Z

This pull request does not contain a staged changelog entry. To create one, use the ./.changes/new-change command. For example:

./.changes/new-change --pull-requests "#2878" --type feature --description "JMESPath evaluation"

Make sure that the description is appropriate for a changelog entry and that the proper feature type is used. See ./.changes/README or run ./.changes/new-change -h for more information.

…-evaluator

mtdowling · 2025-12-09T18:53:48Z

smithy-model/src/main/java/software/amazon/smithy/model/node/NodeJmespathRuntime.java

+
+    @Override
+    public Node createBoolean(boolean b) {
+        return new BooleanNode(b, SourceLocation.none());


Use a cached value. I think Node might already handle this for you.

Node.nullNode() and Node.from(boolean) were not in fact already using cached values, but I fixed that. :)

smithy-model/src/main/java/software/amazon/smithy/model/node/NodeJmespathRuntime.java

mtdowling · 2025-12-09T18:58:15Z

...l-jmespath/src/main/java/software/amazon/smithy/model/jmespath/node/NodeJmespathRuntime.java

+
+    @Override
+    public Node element(Node array, Node index) {
+        return array.expectArrayNode().get(index.expectNumberNode().getValue().intValue()).orElseGet(this::createNull);


This is pretty rough for array indexing. I think we should add a method to ArrayNode to get a value at an index or return null if not found to remove indirection and allocations here.

As in a getOrNull method that returns a possibly-null Node instead of an Optional<Node> as get does?

I ended up adding an elementAt method that should always return a non-null value (since the elements of an ArrayNode should use NullNode rather than null) and throws if the index is out of range. That works better here since the evaluator checks the range already for you. Let me know if that's not what you had in mind.

smithy-model/src/main/java/software/amazon/smithy/model/node/NodeJmespathRuntime.java

smithy-jmespath/src/main/java/software/amazon/smithy/jmespath/evaluation/Evaluator.java

smithy-jmespath/src/main/java/software/amazon/smithy/jmespath/functions/FunctionRegistry.java

mtdowling · 2025-12-09T20:22:20Z

smithy-model/build.gradle.kts

 extra["moduleName"] = "software.amazon.smithy.model"

 dependencies {
+    api(project(":smithy-jmespath"))


I don't love the artifact size hit to smithy-model to unconditionally pull in jmespath. Do we need Node-based evaluation? If so, can it be a bridge package?

Yeah I'd rather move this out

Yes I plan to leverage the Node-based evaluation in the next PR, which will add a new trait that uses JMESPath and wants to validate that positive/negative examples are actually correct.

I've moved the NodeJmespathRuntime class and tests to a separate smithy-model-jmespath package now though.

mtdowling · 2025-12-09T20:27:22Z

smithy-jmespath/src/main/java/software/amazon/smithy/jmespath/evaluation/Evaluator.java

+
+    @Override
+    public T visitFunction(FunctionExpression functionExpression) {
+        Function function = FunctionRegistry.lookup(functionExpression.getName());


It'd be nice if FunctionRegistry also included a way to get all registered functions, and then that could be used to turn runtime function lookup into primitive array index access rather than the current hashmap access. Not sure how though... maybe all builtin functions get assigned a fixed index and functionExpression returns that index or -1 if it's custom. Then the parser can setup the right index, the FunctionExpression getter returns that index, and then maybe add a method to JmesPath runtime called getFunction(FunctionExpression)? or something like that. This would also remove the global function registry and support custom functions.

Yeah I was thinking through this as well. The AST would have to change somehow, perhaps to add a FunctionIndexExpression that you can compile FunctionExpressions to.

I will move all of the Function related types into the same package as the evaluator so that all of them can be package-private, so we can figure this out and support custom functions in a later PR.

Co-authored-by: Michael Dowling <[email protected]>

…hy into smithy-jmespath-evaluator

…things

robin-aws added 30 commits October 31, 2025 15:11

First cut

aceec7c

m

0e49d7b

m

362776c

Fixes

cb00d7d

Cleanup

848ddad

m

3cf227d

comment

2213cb1

Rename package

4924c96

Unshare class for now

37c59da

Undo

34c90f4

Move into smithy-model

9fd957c

Most of an interpreter

7c779c1

m

e3995fc

Complete NodeAdaptor

37d1e4c

Make @contracts a list instead of a map

b868f25

Improve Adaptor interface

3c2cf03

Renames

a457760

First function

77c3436

Merge branch 'main' of github.com:awslabs/smithy into smithy-contracts

e09995e

# Conflicts: # VERSION

Rename to JmespathRuntime, more functions

347c512

length

ead6908

Merge branch 'main' of github.com:awslabs/smithy into smithy-contracts

59c332b

Generic compliance test runner

b8d56ca

smithy-jmespath-tests

78c28df

Fix slice!

c8ae716

Correct multiselect and parsing

36cbf9e

Special case

db17f41

m

ac48d63

Formatting

a635724

Cleanup

27f577b

robin-aws added 8 commits December 4, 2025 15:43

doc build

a008e22

Correct place

eba96d8

remove accidental content

e03149d

Remove @contracts on this branch

97fe1e9

Cleanup

bae6940

spotless

c086ce4

Javadoc and renames

73831ad

spotless

9c557e3

robin-aws requested a review from a team as a code owner December 5, 2025 23:19

robin-aws requested a review from JordonPhillips December 5, 2025 23:19

robin-aws changed the title ~~Smithy jmespath evaluator~~ JMESPath evaluation Dec 5, 2025

HashMap instead of ConcurrentHashMap (need null values)

7178421

robin-aws added 6 commits December 6, 2025 09:01

InheritingClassMap fix

f478763

javadoc typo

633fe5d

m

8648ea3

feature comment and cleanup

a6d462e

Dead class

749103b

Merge branch 'main' of github.com:awslabs/smithy into smithy-jmespath…

219954b

…-evaluator

mtdowling requested changes Dec 9, 2025

View reviewed changes

robin-aws and others added 9 commits December 9, 2025 16:47

PR feedback

6e2b286

Apply suggestions from code review

cffc270

Co-authored-by: Michael Dowling <[email protected]>

Merge branch 'smithy-jmespath-evaluator' of github.com:robin-aws/smit…

d36352b

…hy into smithy-jmespath-evaluator

Fix

5f8101a

m

7a61fbf

Move functions into evaluation package, reduce visibility of several …

507e8b4

…things

Move NodeJmespathRuntime to separate smithy-model-jmespath package

76deec3

ArrayNode.elementAt

71e28d3

Use int for lengths/indexes

00f1ffc

JMESPath evaluation #2878

Are you sure you want to change the base?

JMESPath evaluation #2878

Conversation

robin-aws commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

Testing

Links

Uh oh!

github-actions bot commented Dec 5, 2025

Uh oh!

github-actions bot commented Dec 6, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

robin-aws Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

robin-aws commented Dec 5, 2025 •

edited

Loading

robin-aws Dec 10, 2025 •

edited

Loading