influxdata / influxdata/docs-v2

Differentiate JSON-shape illustrations from real JSON request bodies

Open
#7,179 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.