docs(idempotency): fix misleading idempotent examples

[walmsles]

Issue #, if available: #657

Description of changes:

Updated Idempotency Payments API example and split out JMESPath Function section from Validation utility since also applicable to Idempotency utility. This split seems logical and updated references in both Validation and Idempotnecy documentation to suit.

No changes for Feature Flags documentation required (JMESPath is referenced but not built-in functions specifically)

Added warning around JSON API Idempotency in the Payments example explicitly calling ou the usage of event_key_jmespath which is essential for correct Idempotency for JSON API structures.

Checklist

• Meet tenets criteria
• Update tests
• Update docs
• PR title follows conventional commit semantics

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

---

View rendered docs/utilities/idempotency.md
View rendered docs/utilities/jmespath_functions.md
View rendered docs/utilities/validation.md

[codecov-commenter]

Codecov Report

Merging #661 (da73191) into develop (c8cf3ba) will increase coverage by 0.00%.
The diff coverage is n/a.

@@           Coverage Diff            @@
##           develop     #661   +/-   ##
========================================
  Coverage    99.97%   99.97%           
========================================
  Files          116      116           
  Lines         4846     4866   +20     
  Branches       265      267    +2     
========================================
+ Hits          4845     4865   +20     
  Partials         1        1           

Impacted Files	Coverage Δ
aws_lambda_powertools/event_handler/api_gateway.py	100.00% <0.00%> (ø)
...mbda_powertools/utilities/validation/exceptions.py	100.00% <0.00%> (ø)
...ools/utilities/idempotency/persistence/dynamodb.py	100.00% <0.00%> (ø)
...ities/data_classes/api_gateway_authorizer_event.py	100.00% <0.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update c8cf3ba...da73191. Read the comment docs.

[to-mc]

Thanks for this @walmsles! A few suggested changes inline - definitely a good improvement for the docs 😊

[walmsles]

@cakepietoast - accepted review suggestions - documentation IS hard, thanks for the improvements 👍

[to-mc]

LGTM!

[heitorlessa]

Absolutely loved it!! Now that we're exposing JMESPath Functions in its own doc, I think it's fair we expose it for everyone to use with jmespath whether they use idempotency or validation.

Since jmespath dependency is brought along, they will be able to extract things from JSON more easily too.

[walmsles]

@heitorlessa also within Feature Toggles - although that doc references JMESPath site directly I noticed so within the scope of this change left that alone. Maybe want to re-align those docs too?