influxdata / influxdata/docs-v2
Differentiate JSON-shape illustrations from real JSON request bodies
- Dominant language
- JavaScript
- Stars
- 82
- Forks
- 326
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 82
Description
## Background
In several places in our docs, API request body samples contain a long Flux/SQL script as a JSON string value. Authors have historically formatted these with `\` line continuations and unescaped inner `"` for readability:
```text
{
"script": "from(bucket: \"example-bucket\")\
|> range(start: -task.every)\
|> filter(fn: (r) => r._measurement == \"mem\" ...)",
"language": "flux"
}
```
These are not valid JSON, but they're also not literal — they're shell/curl-style examples where bash line continuation joins the lines before the JSON parser sees the body. The `\` and unquoted-inner-`"` are docs-readability conventions, not literal request bodies.
Today this means the blocks fall back to a `text` fence (no syntax highlighting, no parse-lint coverage). PR #7170 made that explicit during the JSON lint cleanup.
## Problem
Readers can't tell from a `text` fence whether a block is:
- A real JSON request body (escape it, paste it, send it)
- A JSON-shape illustration (you'd never send this verbatim — you'd build it from the prose)
That ambiguity is fine for a couple of examples but recurs across `process-data/*`, `api-guide/*`, and the v1 Kapacitor API docs.
## Proposal
Standardize on **two paired blocks** for any request body that embeds a multi-line script as a JSON string field. Pattern, applied as a reference in [`content/shared/influxdb-v2/process-data/get-started.md` "Full example task with invokable script"](https://github.com/influxdata/docs-v2/blob/master/content/shared/influxdb-v2/process-data/get-started.md):
> The Flux for the `script` field:
>
> ` ```js ` ... readable Flux block ... ` ``` `
>
> The full request body, with the script encoded as a JSON string (inner quotes escaped as `\"`, line breaks as `\n`):
>
> ` ```json ` ... valid JSON with `\n`-escaped script ... ` ``` `
Benefits:
- Both blocks lint clean (Flux block can stay `js`-highlighted; JSON block actually parses).
- Reader sees the script in its native form.
- The encoding step is taught explicitly — no hidden shell magic.
For places where the shell wrapping itself is the lesson (env-var interpolation, heredoc usage), use `tabs-wrapper` with "Request body" / "curl command" tabs instead.
## Files to convert
Known instances (others may exist):
- [ ] `content/shared/influxdb-v2/process-data/get-started.md` — "Define and use scripts" section (`aggregate-intervals` block, ~line 147)
- [x] `content/shared/influxdb-v2/process-data/get-started.md` — "Full example task with invokable script" (`aggregate-intervals-and-export` block, ~line 220) — converted in #7170 as the reference
- [ ] `content/influxdb/cloud/api-guide/api-invokable-scripts/_index.md` — `filter-and-group` block (~line 126)
- [ ] Audit remaining `\`\`\`text` blocks where the body is JSON-shaped to find others
## Out of scope
- Telegraf-generated content under `content/telegraf/v1/{input,output,processor}-plugins/` — those are synced from `influxdata/telegraf` and need upstream PRs.
- Real `RECORD BATCH` / msgpack output blocks — those genuinely aren't JSON and stay `text`.
## Reference
PR #7170 fixed JSON parse failures across `content/` and surfaced this pattern. See review thread for the trade-off discussion that led to this proposal.
Contributor guide
No contributing guide indexed for this repository
Research direction
Read the converted “Full example task with invokable script” reference in content/shared/influxdb-v2/process-data/get-started.md, then inspect the unchecked “Define and use scripts” block and content/influxdb/cloud/api-guide/api-invokable-scripts/_index.md. Convert applicable JSON-shaped text fences into paired readable-script and valid-JSON blocks, and audit for other matching cases while leaving the listed out-of-scope content unchanged.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- json, markdown, shell, sql
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 74/100