DOC-6994 Document JSON HIGHLIGHT/SUMMARIZE support and limitations [PARKED]

[dwdougherty]

Documents JSON HIGHLIGHT/SUMMARIZE behaviour after MOD-16530 relaxes the engine's blanket rejection.

The canonical rules now live in one ## JSON indexes section on the Highlighting page; indexing/_index.md, ft.search.md and administration/overview.md point at it instead of restating. Before this change all three disagreed with each other and with the engine — indexing/_index.md already described roughly the post-fix behaviour and shipped a worked example, while the engine had rejected every JSON highlight since 2024. Two rules were never documented anywhere: JSON requires an explicit RETURN, and a single-value JSONPath resolving to an array or object is accepted but silently skipped.

⚠️ Do not merge yet

The fix is not in any released version. The latest tags on the affected lines are v8.4.10, v8.6.8, v8.8.0 and v8.10.0; the fix needs 8.4.13 / 8.6.10 / 8.8.1 / 8.10.1. The 8.6 backport (RediSearch#11046) is still open. Merging now would tell every current reader that JSON highlighting works when the engine still returns HIGHLIGHT/SUMMARIZE is not supported with JSON indexes.

Both pages carry a <!-- TODO(DOC-6994) --> comment where the version statement goes. Those must be resolved before merge.

Park manifest

Ticket: DOC-6994
Parked at: 2026-08-25
Trigger to pick up: the 8.4 line ships the fix — a non-prerelease tag v8.4.13 (or later 8.4.x) exists and PR #11048's merge commit d526e7ec03931f36469a7f216b76e1ec089f67da is an ancestor of it (gh api repos/RediSearch/RediSearch/compare/d526e7ec03931f36469a7f216b76e1ec089f67da...v8.4.13 --jq '{status,behind_by}' → behind_by: 0) — and PR #11046 (8.6) has merged, so the version statement can name every affected line.
Labels: parked, do not merge yet

Pinned sources (state observed at park time, 2026-08-25)

Backports target the release branches directly, so these are the branches the releases are cut from.

Source	State at park time	Re-fetch
RediSearch#9410 — primary impl, master	merged, merge bd3ec5dca46c22b54f0673104b64fd9020febade, head e9d8b09f3b36ee141e48553a66f309c2f088985e, updated 2026-08-21T16:29:33Z	gh api repos/RediSearch/RediSearch/pulls/9410 --jq '{state,merged,merge_commit_sha,head_sha:.head.sha,base:.base.ref,updated_at}'
RediSearch#11106 — follow-up, master	merged, merge a3a09eb58e2ec51940fbd1c1402a2c80a8032a04, updated 2026-08-24T23:54:41Z	gh api repos/RediSearch/RediSearch/pulls/11106 --jq '{state,merged,merge_commit_sha,updated_at}'
RediSearch#11048 — backport, base 8.4	merged, merge d526e7ec03931f36469a7f216b76e1ec089f67da, updated 2026-08-25T00:57:39Z	gh api repos/RediSearch/RediSearch/pulls/11048 --jq '{state,merged,merge_commit_sha,updated_at}'
RediSearch#11046 — backport, base 8.6	OPEN (the blocker), head b8bf56a87f20f7f307d06aea4247bff103a3e9cc, updated 2026-08-24T23:06:50Z	gh api repos/RediSearch/RediSearch/pulls/11046 --jq '{state,merged,merge_commit_sha,head_sha:.head.sha,updated_at}'
RediSearch#11044 — backport, base 8.8	merged, merge fe67f90b86ab478c0060e649670ee1b83e76b2b9, updated 2026-08-25T09:46:32Z	gh api repos/RediSearch/RediSearch/pulls/11044 --jq '{state,merged,merge_commit_sha,updated_at}'
RediSearch#11043 — backport, base 8.10	merged, merge 553687a37d9905d6a1538aa22a01f137e8c14a5c, updated 2026-08-25T01:42:10Z	gh api repos/RediSearch/RediSearch/pulls/11043 --jq '{state,merged,merge_commit_sha,updated_at}'
RediSearch#11049 — backport, base 8.2	closed WITHOUT merging (merged: false), updated 2026-08-24T18:11:20Z. Consistent with Jira having no 8.2.x fix version — so 8.2 does not get the fix.	gh api repos/RediSearch/RediSearch/pulls/11049 --jq '{state,merged,updated_at}'
RediSearch#11047 — backport, base 8.6-rse	merged, merge 518ca89cbc9830d505cea94f35bd999f4ad396f8, updated 2026-08-25T07:45:46Z	gh api repos/RediSearch/RediSearch/pulls/11047 --jq '{state,merged,merge_commit_sha,updated_at}'
RediSearch#11045 — backport, base 8.8-rse	merged, merge bfb2aa1186d9272166f6e76bedc12805ef04a01a, updated 2026-08-24T23:46:39Z	gh api repos/RediSearch/RediSearch/pulls/11045 --jq '{state,merged,merge_commit_sha,updated_at}'
Release tags on affected lines	latest are v8.4.10, v8.6.8, v8.8.0, v8.10.0. v8.4.13 does not exist (404). Nothing shipped.	gh api 'repos/RediSearch/RediSearch/tags?per_page=100' --jq '.[].name' | grep -E '^v8\.(4|6|8|10)\.'
MOD-16530	status In Backport, unresolved. Fix versions all released: false: RediSearch 8.4.13, 8.6.10, 8.8.1, 8.10.1, RediSearchEnterprise 8.6.11 / 8.8.5, Open Source 8.12 (2026-10-30)	Atlassian MCP getJiraIssue MOD-16530
MOD-17663 — projection-alias support	status To Do, no fix versions, updated 2026-08-16. Would invalidate the "raw JSONPath aliases cannot be highlighted" bullet if it lands.	Atlassian MCP getJiraIssue MOD-17663

Observed shape the page assumes

Semantics — confidence HIGH. These held identically across dialects 1–3+ in the merged test suite, and are the shape of the page:

• Single-value JSONPath to a scalar, with RETURN naming the field → works, output matches HASH for the same content.
• No RETURN, or RETURN 0 → rejected. Rationale documented on the page: without RETURN, JSON loads as one serialized value so individual fields never reach the highlighter.
• Multi-value JSONPath anywhere in the returned/highlighted set → rejected. Rationale: each value is indexed separately with its own byte offsets.
• Single-value JSONPath resolving to a JSON array or object → accepted, highlighting skipped, original loaded value returned, no error.
• HASH unchanged; RETURN not required.

Identifiers — confidence LOW. Every string below is transcribed from a diff and a test suite, never from a running engine, because no release contains the fix. Error strings are prose in QueryError_SetError calls and are exactly the kind of thing that gets reworded between merge and release. Tick each one off individually on unpark:

1. HIGHLIGHT/SUMMARIZE on JSON indexes requires RETURN with explicit field names — seen in src/aggregate/aggregate_request.c, AREQ_ApplyContext, PR #9410 diff; asserted as no_return_error in tests/pytests/test_json.py.
2. HIGHLIGHT/SUMMARIZE is not supported for JSON fields with multi-value JSONPath — seen in src/aggregate/aggregate_request.c, AREQ_HasMultiValueHighlightFields, PR #9410 diff; asserted as multi_value_error.
3. Property `alias` is not in schema — asserted as alias_error in tests/pytests/test_json.py. Pre-existing schema validation, not added by #9410 — so if it's absent on unpark the cause is a different change, not a rename.
4. Reply body Noise-cancelling <b>Bluetooth</b> headphones, and description left un-highlighted when HIGHLIGHT FIELDS 1 name is used — output shape from test_highlight_single_value_json. The doc example reuses that fixture's content but its own key (item:1) and index name (itemIdx).
5. RETURN 0 producing the same error as omitting RETURN — asserted in test_json.py, not separately stated in the C diff.
6. Multi-value rejection applying regardless of schema field type — this comes from PR #11106 only, not from the #9410 diff. #11106's body claims it "matches the validation follow-up already included in the active release backports", but the backports merged both before and after #11106 landed on master and I did not read their diffs to confirm. If it's absent, the page's "whatever its schema type" clause is wrong.

Where the record and the source disagree: DOC-6994's description says "Fixed in 8.4 onward". The GitHub PR list initially looks like an 8.2 backport merged too; it did not (merged: false). Trust the merged field, not the closure.

Re-check checklist

Harvested from the branch's /reflect trailers, plus predicted-to-change items.

Highest risk:

• Resolve both <!-- TODO(DOC-6994) --> version comments — advanced-concepts/highlight.md and indexing/_index.md. Confirm the exact patch version per line with Omer Shadmi / Abid Saudagar. Follow the maintenance-line wording precedent at administration/configuration.md → search-bg-index-sleep-duration-us. Current evidence says 8.4 / 8.6 / 8.8 / 8.10 / OSS 8.12 and not 8.2.
• Re-verify all six LOW-confidence identifiers above, one verdict each, against a build that actually has the fix.
• Confirm identifier 6 (type-independent multi-value rejection) is present in the shipped 8.4 backport — read AREQ_HasMultiValueHighlightFields on the release tag rather than trusting #11106's PR body.
• Run the four JSON examples on a real build and replace any transcribed reply that differs. From the branch Constraint trailer: every FT.SEARCH reply on the Highlighting page came from pytest assertions, not execution.

Also:

• From the branch Directive trailer: a SUMMARIZE reply body and the array-skip reply were deliberately omitted because their output is dialect-dependent and the tests only assert substring containment. Add them only with a real build — do not reconstruct them by hand.
• Check whether MOD-17663 shipped in the same release. If it did, the "Raw JSONPath aliases cannot be highlighted" bullet on highlight.md is stale.
• Re-sync data/commands_redisearch.json (lines ~1061, ~1112) and data/commands_core.json (~11354, ~11409). They still carry the old blanket "not currently supported" summaries; upstream commands.json was updated in #9410. Deliberately not hand-edited — these are regenerated at release-docs time, so the edit would have been silently superseded.
• Confirm the bannerText substitution still reads correctly. /park Step 4 normally wants a page-level bannerText; it was deliberately not added, because it banners the entire page and would misdescribe ~900 lines of GA content on ft.search.md. The section-level version statement is the guard instead. Not an oversight.
• From the branch Gaps trailer: tmp/RediSearch was last fetched 2026-07-30 and its master predates and contradicts this fix — its aggregate_request.c still carries the blanket rejection on all of 8.0–8.10. Do not use it to verify. Re-fetch or read upstream via gh.
• Re-run hugo and confirm the five cross-links still resolve (#json-indexes anchor on highlight.md, linked from indexing/_index.md ×2 and administration/overview.md).

On unpark, then

When the trigger fires, run /unpark <PR>. It reconciles the docs against the now-settled source and takes the PR through the normal /reflect → /finalize pipeline to merge. /finalize is deferred until then — squashing now would discard the episodic trailers this manifest was built from. The do not merge yet guard holds until /finalize completes.

---

Note

Low Risk
Documentation-only changes with no runtime impact; the main risk is publishing before the engine fix releases, which the PR explicitly guards with TODOs and a park manifest.

Overview
Documents JSON index behavior for FT.SEARCH HIGHLIGHT and SUMMARIZE after the engine stops rejecting them outright (MOD-16530). The canonical rules live in a new ## JSON indexes section on the Highlighting page: explicit RETURN is required, multi-value JSONPaths are rejected with named errors, RETURN aliases cannot be used in HIGHLIGHT/SUMMARIZE FIELDS, and single-value paths that resolve to arrays/objects return unhighlighted values without error.

ft.search.md, the search technical overview, and JSON indexing pages no longer restate conflicting snippets—they add short JSON caveats and link to #json-indexes. The indexing guide also clarifies RETURN 0 rejection, expands the highlight note (including array/object skip), documents the multi-value error under index limitations, and sets hideListLinks: true on the indexing section front matter.

<!-- TODO(DOC-6994) --> placeholders remain for version/maintenance-line wording until the fix ships in released builds; the PR description marks it parked / do not merge until then.

^{Reviewed by Cursor Bugbot for commit 47ac77e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

DOC-6994

[github-actions]

🧠 Redis Memory

Found 7 related items from repository history:

• PR — DOC-6842 Add redis-rb (Ruby) JSON docs [PARKED]

  DOC-6842 — redis-rb (Ruby) JSON docs

• PR — DOC-6843 Add redis-rb (Ruby) Query Engine docs: queryjson [PARKED]

  Preemptive docs for redis-rb's Query Engine (RediSearch / FT.*): a new "Index and query documents" page for Ruby (`content/develop/cli

• PR — DOC-6957 Add Ruby (redis-rb) array data type examples [PARKED]

  DOC-6957 — Ruby (redis-rb) array data type examples

• PR — DOC-6854 Add redis-rb (Ruby) vector search docs: vecsearch page + ruby_home_query_vec [PARKED]

  Preemptive docs for redis-rb's Query Engine vector search: a new "Index and query vectors" page for Ruby (`content/develop/clients/ruby/

• PR — DOC-6939 Correct stale document count in the NDJSON feed docs

  Fixes the stale document count on the AI agent resources page — item A1 of DOC-6939.

• Commit — DOC-6994 Document JSON HIGHLIGHT/SUMMARIZE support and limitations

  DOC-6994 Document JSON HIGHLIGHT/SUMMARIZE support and limitations

• PR — DOC-6829 Add preemptive Spring Data Redis JSON docs [PARKED]

  Summary

Memory updated at 47ac77e

[github-actions]

Staging links:
https://redis.io/docs/staging/DOC-6994/commands/ft.search/
https://redis.io/docs/staging/DOC-6994/develop/ai/search-and-query/administration/overview/
https://redis.io/docs/staging/DOC-6994/develop/ai/search-and-query/advanced-concepts/highlight/
https://redis.io/docs/staging/DOC-6994/develop/ai/search-and-query/indexing/

[andy-stark-redis]

Couple of minor comments but otherwise LGTM.

[dwdougherty]

Thank you for the review, @andy-stark-redis!