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

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.

I think we should just add a method that return the value or null. It's more general purpose and covers your use case too.

Sure, it means an extra range check in my case but I'm not concerned about that. Operations that will access lots of array elements will use asIterable instead anyway.

Oh, but do you want to return null if the array is actually storing a NullNode at the index, and not just if the index is out of range? That's less ideal here since I actually want the NullNode, but I could work with that.

I was thinking to return a regular Java null, basically just a pass through to Array.get, even throwing IndexOutOfBoundsException if out of range. Thoughts?

Yup that's what I had the first time. :) Agreed on just throwing for out of range. But AFAICT an ArrayNode should only ever have non-null elements and use NullNode instead. e.g. this check in withValue. So that means passing through to List.get should never return a Java null. I think that's the right call though.

Discussed offline and I'm going to go with returning a NullNode if the element is a NullNode or if the index is OOB. Will pull the Node changes into the next PR along with smithy-model-jmespath though.

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.

For this PR can we leave out smithy-model-jmespath too?

Sure I could move that to the next PR that will actually use it, that makes sense.

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

Co-authored-by: Michael Dowling <michael@mtdowling.com>

…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 4 commits December 5, 2025 12:09

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 13 commits December 9, 2025 16:47

PR feedback

6e2b286

Apply suggestions from code review

cffc270

Co-authored-by: Michael Dowling <michael@mtdowling.com>

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

Tweak ArrayNode.elementAt

4e64aae

Back to first ArrayNode.elementAt version

ae683d9

Save smithy-model-jmespath for the next PR

0625736

Save Node changes to next PR too

dbbfb75

JMESPath evaluation #2878

Are you sure you want to change the base?

JMESPath evaluation #2878

Uh oh!

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!

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!

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!

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!

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