DOC-6829 Add preemptive Spring Data Redis JSON docs [PARKED] - #3611
Open
andy-stark-redis wants to merge 2 commits into
Open
DOC-6829 Add preemptive Spring Data Redis JSON docs [PARKED]#3611andy-stark-redis wants to merge 2 commits into
andy-stark-redis wants to merge 2 commits into
Conversation
Document the new template-layer JSON API from the in-progress SDR PR spring-projects/spring-data-redis#3390 ahead of its release. The page lives under content/integrate/spring-framework-cache/, which despite the directory name is the Spring Data Redis section (LinkTitle "Spring Data Redis"), alongside the cache and geo-failover recipes. The non-obvious call: no per-client split. RedisJsonTemplate/JsonOperations is client-agnostic and identical whether Jedis or Lettuce backs the connection — the clients diverge only in internal converters/path types below the API surface, with full feature parity. So one set of examples serves both. Examples are inline java (not runnable TCE snippets) because the feature isn't in the client example repos yet, and a bannerText flags the API as unreleased and subject to change. Learned: SDR JSON template API is unified across Jedis/Lettuce; docs based on an unmerged PR Directive: keep the JSON examples client-agnostic — do not split into Jedis vs Lettuce variants Recheck: when spring-data-redis#3390 merges and ships — re-verify method signatures, bean/serializer wiring, and convert examples to runnable TCE doctests Gaps: code examples untested; signatures and API shape read from an in-progress, still-reviewed diff Ticket: DOC-6829 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
andy-stark-redis
added
do not merge yet
parked
Contributor
andy-stark-redis
added a commit
that referenced
this pull request
Jul 22, 2026
Renamed the parked-PR thaw skill from `/pickup` to `/unpark` — directory, frontmatter, title, and prose — to free the `/pickup` name for another skill where it fits better; `park`/`unpark` also reads as a cleaner verb pair. Updated the two files that reference it, `/park` and the shared `_shared/park-manifest.md` contract, so the pairing stays consistent. The three parked PRs that instructed `/pickup <n>` (#3611, #3641, #3652) were updated out-of-band so no stale invocation survives. Approved by dwdougherty; Cursor Bugbot clean. Directive: Two "pickup" strings are left un-renamed on purpose — the historical .claude/state/assess-comments.coverage.md audit log (it records the skill's old name as it was at the time; renaming falsifies history) and the "Trigger to pick up:" manifest field name in park-manifest.md (a header field, not the skill name). Don't "fix" them in a follow-up grep-and-replace. Ticket: DOC-6876 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This was referenced Jul 31, 2026
The API this page was written against shipped in spring-data-redis 4.2.0-M1 (2026-08-21). Reconciling the page against the released source fixed six defects, four of them compile errors. Still parked: 4.2.0-M1 is a milestone, not a GA release, so the API can still move before 4.2.0. Fixed: - Bean wiring. `RedisJsonTemplate<K>` has ONE type parameter (the key type) and is constructor-injected, not a no-arg bean with setters. The page's `RedisJsonTemplate<String, User>` + `setJsonSerializer()` form does not exist in any released version. - `JacksonRedisJsonSerializer` and `StringRedisJsonTemplate` do not exist. - `JsonResult` is not generic, and `getValue()` is not one of its methods. Values come out via `as(Class)` / `asString()` / `map()`. - `value(key).paths(...)` exists on nothing. `paths` is a top-level `JsonOperations` method; the specs only carry `path(String)`. - Added `setIfPresent`, which exists as a default alongside `setIfAbsent`. - Banner rewritten: it still described #3390 as an in-progress PR. The most useful thing this taught: the park manifest's own correction note was itself wrong, and following it would have produced a second compile error. It offered `JacksonJsonRedisSerializer` and `GenericJacksonJsonRedisSerializer` as interchangeable replacements. They are not. `JacksonJsonRedisSerializer<T> implements RedisSerializer<T>`, while the constructor demands `RedisJsonSerializer` — only the two `Generic*` classes implement it. Identical-looking names, incompatible types, and the byte-identical blob check that discharged the "signatures" item could never have caught it, because these classes live in files the manifest never pinned. A discharge is only as wide as its pins. Second lesson: the manifest declared the fluent surface "correct as written" after a signature diff. Two of the six defects were in that surface. A signature diff proves nothing moved; it does not prove the page ever matched. Learned: a park manifest's correction notes need the same scepticism as the page they correct; a blob-identity discharge only covers the files it pins Ticket: DOC-6829 Constraint: RedisJsonTemplate's 3rd ctor arg must implement RedisJsonSerializer — only GenericJacksonJsonRedisSerializer (Jackson 3) and GenericJackson2JsonRedisSerializer (Jackson 2) do. Rejected: JacksonJsonRedisSerializer as the document serializer | implements RedisSerializer<T>, not RedisJsonSerializer; will not compile Recheck: when spring-data-redis 4.2.0 reaches GA — re-diff both blobs at the GA tag and replace the {version} placeholder Gaps: no snippet was compiled against the 4.2.0-M1 artifact; every signature was read from source at the tag, which is weaker than a build Directive: BoundJsonOperations is absent at 4.2.0-M1 (0 hits, core/ listing confirms) — do not re-derive that check
Contributor
🧠 Redis MemoryFound 5 related items from repository history (5 new this commit):
Memory updated at 363dd62 |
10 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Preemptively documents the new template-layer JSON API in Spring Data Redis (DOC-6829), ahead of its upstream release. Adds a new recipe page under the Spring Data Redis section and links it from the section index.
content/integrate/spring-framework-cache/json.mdcontent/integrate/spring-framework-cache/_index.mdWarning
This PR is parked — do not merge. The docs are written against an unreleased, still-under-review upstream PR (spring-data-redis#3390). Merge only after the feature ships and the manifest below has been reconciled (see
/unpark).Park manifest
Ticket: DOC-6829
Parked at: 2026-07-10
Trigger to pick up: the JSON API is present in a released
spring-data-redisversion — testably,gh api "repos/spring-projects/spring-data-redis/contents/src/main/java/org/springframework/data/redis/core/RedisJsonTemplate.java?ref=<tag>"returns 200 at a release tag newer than4.1.0. The expected first such release is4.2.0-M1. ✅ FIRED 2026-08-21 —4.2.0-M1shipped and contains the API (see the 2026-08-25 update below). The remaining blocker is no longer upstream at all: it was the milestone-vs-GA decision in the checklist below — DECIDED 2026-08-26: hold for4.2.0GA. New trigger: a non-prerelease4.2.0tag containingcore/RedisJsonTemplate.java. The page is now API-correct against4.2.0-M1and stays parked purely for the GA gate.Labels:
parked,do not merge yetPinned sources (state observed at park time)
e35714beca1c1ac46f0cb8a325ac95b9e6199d0f, basemain, milestone: none (no target version), updated 2026-07-08To diff on unpark: re-read
JsonOperations.javaandRedisJsonTemplate.javaat the released tag. Do not gate on the PR'smergedflag — see the correction below.Observed API shape the page assumes (LOW confidence at park time — superseded by the 2026-08-13 reconciliation note above)
RedisJsonTemplate:value(key),array(key),string(key),bool(key)..path("$.jsonpath")chaining;set/setIfAbsent/get/paths.append,length,indexOf,trim. String:append,length. Boolean:toggle. Document:mergeWith.RedisJsonTemplate+JacksonRedisJsonSerializer(Type.class)over the existingRedisConnectionFactory.Re-check checklist (work these on unpark)
363dd624). NowRedisJsonTemplate<String>(one type param) built via the 3-arg constructor withGenericJacksonJsonRedisSerializer.builder().build(). Read correction 1 in the 08-26 note before touching this — the fix originally prescribed here would not have compiled. Original text:RedisJsonTemplate<K>is single-parameter and constructor-injected, and bothJacksonRedisJsonSerializerandStringRedisJsonTemplatedo not exist. The snippet as written will not compile. See the 2026-08-13 reconciliation table.363dd624).JsonResultde-genericised;getValue()(which does not exist) replaced withas(User.class);value(key).paths(…)replaced with the top-levelpaths(key, …)+asString(). Original text:JsonResultis not generic; replaceJsonResult<User>/JsonResult<String>withJsonResult+as(Class)/asString().4.2.0-M1tag: both blobs are byte-identical to the 2026-08-13mainsnapshot (0d79685d/23849,b1577231/22416), so by this item's own rule no signature can have moved. Re-open only if unparking against a different tag than4.2.0-M1.getValue()andvalue(key).paths(…)were both bogus. A signature diff proves nothing moved; it does not prove the page ever matched.opsForJson()— DONE 2026-08-25. Re-checked at the released4.2.0-M1tag: absent from bothRedisOperations.javaandRedisTemplate.java(0 occurrences each, against a positive control ofopsForHash= 1, so this is a real absence and not a broken check).RedisJsonTemplatestays the entry point; no page restructure needed. Item closed — do not re-derive.4.2.0GA. The{version}placeholder stays until a non-prerelease4.2.0ships; then replace it and re-diff both blobs at that tag. Rationale: M1 is not API-frozen, and the same-day GA releases (4.1.1,4.0.7) deliberately omit the API, so there is no GA option short of4.2.0. Original text: replace the{version}placeholder in the Maven/Gradle snippets with the first release that includes JSON support. As of 2026-08-25 that is4.2.0-M1, a milestone/pre-release; the GA releases cut the same day (4.1.1,4.0.7) deliberately omit the API, so there is no GA option short of4.2.0itself. Decide explicitly whether a milestone build is enough to publish against — if yes, the page must say the API is milestone-only and name the milestone repository; if no, hold for4.2.0GA and re-run the blob diff at that tag.BoundJsonOperations— DID NOT LAND, closed 2026-08-26. Absent fromcore/at4.2.0-M1(directory listing shows onlyJsonOperations,RedisJsonOperations,RedisJsonTemplate; code search 0 hits). No bound-operations section needed. Do not re-derive. Original text: explicitly deferred in the PR. If it lands before GA, add a bound-operations section.setIfPresent— DONE 2026-08-26. Now covered on the page alongsidesetIfAbsent. Original text: exists onmainand the page doesn't mention it. Decide whether to cover it alongsidesetIfAbsent.javablocks to tested TCE (clients-example) doctests once the feature reaches the client example repos.4.2.0-M1tag: bothjedis/andlettuce/ship*JsonCommandsand*ClusterJsonCommands. Re-confirm at the GA tag. Original text: re-confirm the "works with either" claim; the two clients could ship support on different timelines.main; re-run link checks. Partially done 2026-08-26: all 7relreftargets re-verified as resolving, andbannerTextwas rewritten (it still described DEV/RI: document new search workspace #3390 as in-progress). The branch has not been rebased ontomain— deliberately deferred, to keep this parked branch free of merge noise until the GA unpark.On unpark, then
Update the docs to reconcile, remove the
bannerTextwarning, drop theparked/do not merge yetlabels, run/reflect(record what actually changed vs predicted) and/finalize(the durable squash — deferred until now on purpose so these re-check notes survive).🤖 Generated with Claude Code
Note
Low Risk
Documentation-only changes with no runtime or security impact; publishing still depends on the milestone-vs-GA version decision noted in the PR.
Overview
Adds documentation for Spring Data Redis’s template-based JSON API (DOC-6829): a new recipe under Spring Data Redis and a bullet on the section index linking to it.
The
json.mdpage covers requirements (Redis JSON, Lettuce/Jedis, Jackson), Maven/Gradle setup with a{version}placeholder,RedisJsonTemplatebean wiring, and fluent examples for whole-documentvalue()ops, JSON path updates (setIfAbsent/setIfPresent),array()/string()/bool()helpers, andmergeWith(). It includes abannerTextwarning that JSON support is only in the4.2.0-M1milestone until GA, plusrelatedPagesto Redis JSON and client docs.Reviewed by Cursor Bugbot for commit 363dd62. Bugbot is set up for automated code reviews on this repo. Configure here.