Request bodies

Supported JSON object bodies open in Form view, with schema metadata and controls arranged side by side. JSON remains available for raw editing; the selector has only Form and JSON. Open Schema controls within Form for detailed field editing. For object schemas with declared properties or homogeneous array schemas, open Schema controls in Form to edit individual values. Root arrays use indexed item labels and the same add/remove controls as nested arrays. Strings use text inputs, password/write-only strings are masked, booleans and enums use selectors, and nullable properties have an explicit null control. Numbers retain their original JSON number tokens, including large integer IDs and precise decimals. Nested objects expand into their own controls, including referenced and recursive schemas. Homogeneous arrays expose item controls, including object items and nested arrays, with Add item and Remove actions. Each expanded object or array has a Fields / JSON switch; unsupported schemas use JSON within their field. Strings inside write-only objects and arrays remain masked in field controls. Sensitive enum options and constants use concealed labels; the raw JSON mode still exposes actual values for review.

Object allOf schemas expose fields when their branches have disjoint property definitions. Local references and OpenAPI 3.1 reference siblings work in these compositions; required names are combined and read-only/write-only annotations remain effective. Repeated property names, non-object branches and additional composition constraints (including closed-object policies, unions and conditionals) keep JSON editing. This conservative projection does not merge conflicting definitions or claim full schema validation.

Choose a root schema branch

JSON bodies with one root oneOf or anyOf can expose an Editing schema chooser, bounded to eight branches. Select a branch, then open Schema controls in Form when that projection supports the current object or homogeneous array. Selection changes the available controls without modifying the body, selecting an example, discarding other properties or inferring which branches validate. Names use branch titles or numbered labels. OpenAPI 3.0 reference siblings remain ignored; 3.1 sibling constraints remain an intersection. Compatible common object fields and required names are combined through the same conservative allOf projection.

Switching a root branch discards incomplete field drafts throughout the body and retains the last valid body. Valid values, unknown properties, read-only values and exact numeric tokens remain until explicitly edited. A mismatched const, including a discriminator value, has a Use fixed value action; selecting the branch alone never writes it. Sensitive constants keep concealed labels. The API still enforces oneOf exclusivity, anyOf matching, required fields and other constraints. Snippet redaction continues checking all original branches, including branches that are not displayed.

The chooser supports JSON body roots, nested properties and individual array items. Simultaneous oneOf/anyOf, more than eight choices per union, scalar-root controls, unresolved references, overlapping common properties and unsupported sibling constraints keep JSON editing. No automatic discriminator inference or assignment is performed. Form-urlencoded and multipart encoders keep their existing schema restrictions and do not use this chooser. schemaVariants(schema, schemas, legacy) from @davidniessen/doctopus-contracts exposes the same bounded editing choices to integrations; it does not validate body instances.

Choose nested branches

Within Schema controls, an object property or array item with a supported direct union has its own Editing schema chooser. Choices are tied to the actual typed path; a literal payload.name property is independent from payload → name. Different array items can choose different branches. Selecting a branch changes its controls without altering data or implying that the instance matches that branch. Existing required/type/constraint rules still apply.

Changing one nested branch discards incomplete drafts only in that subtree. Other incomplete drafts remain visible and continue blocking Send request. Descendant choices reset when their parent branch changes. Switching a container to JSON, omitting it or setting it to null clears choices beneath that container while retaining its own selection. Returning the entire body to JSON clears all nested choices. Media/example changes and closing the playground reset the editor session as before; choices are not persisted.

Adding/removing array items clears item choices and drafts throughout that array before indexes change; valid values and drafts outside it remain. A newly added union item may start as null. After selecting an object/array branch, Start empty object/array explicitly initializes that empty container; it does not populate required values. Other values remain until explicitly edited. A selected read-only branch retains its data and selector while disabling its field controls, so another branch can still be chosen.

Nested choices share the existing 100-field/item, eight-container and composition limits with the rest of the body. A recursive union cannot start an independent editor budget. Over-budget or unsupported subtrees retain local JSON editing while ordinary siblings stay editable. Snippet redaction continues using the complete original schema graph, including inactive branches and inherited write-only containers.

Edit fields

The default Form view uses rounded sections matching Authorization, Headers and Query parameters. Each declared property shows its name, type, required badge and description beside its input. Required fields appear first; Expand optional fields reveals the optional controls without changing the body. Existing values remain in the request when a section is collapsed. Add body field opens a custom property form with an editable name and JSON type. Optional fields expose remove and include controls that retain omitted drafts. Required and read-only fields stay visible; use JSON to test bodies that omit required properties. Password/write-only inputs are masked. Use the gear button for nested schema controls or choose JSON for raw editing.

Form edits update the same body used by examples and actual requests, including logical form-urlencoded and multipart text values. Number tokens and nested values retain their precision. Duplicate keys, missing names and incomplete typed values block sending until corrected; switching editors retains the last valid body. The target API still enforces required fields and other schema constraints. Scalar roots, empty property names, more than 100 properties and unsupported schemas retain JSON editing. Mock response options follow the request example, with matching section widths and header sizing.

Use the include checkbox to add or omit a property. New values use an explicit constant, default or example when available; otherwise the editor starts with an empty value of the declared type. Required labels remain visible. Unknown properties and existing read-only properties are retained when another field changes; edit those values through JSON. Read-only properties are excluded from the field controls. A const property displays its fixed value and offers an explicit replacement action when the current JSON representation differs.

Incomplete numeric or collection edits disable Send request and replace the snippet with an error. The underlying body keeps its last valid value until the field input is valid. Returning to JSON discards incomplete field drafts and shows that last valid body. Switching an individual object or array between Fields and JSON discards incomplete drafts within that container; omitting it also clears its discarded errors. Adding or removing an array item discards incomplete drafts and per-item branch choices throughout that array before indexes change, while retaining valid values. Keyboard focus moves to the added or nearest remaining item, or the Add item button for an empty array. Valid edits preserve unrelated siblings, unknown properties and read-only values at every level. Field editing checks JSON syntax and the immediate declared value type; it does not replace full JSON Schema validation or the target API's constraints. Required fields, patterns, bounds and cross-field rules still apply.

Precision and editing limits

Editing fields uses a JSON syntax tree rather than converting number tokens to JavaScript floating-point numbers. Updating a name does not round an unrelated ID such as 9007199254740993, a precise decimal or an exponent value. Unknown nested values retain their numeric tokens too. Formatting and equivalent string escapes may change when the body is rewritten.

The field editor accepts at most 1 MiB of UTF-8 JSON, 32 JSON nesting levels and 10,000 values. Expanded controls share a budget of 100 fields/items across at most eight container levels, with at most 100 declared properties per object and 50 items per array. A nested container that exceeds these limits uses a local JSON editor while ordinary siblings remain editable. Unsupported object compositions and unselected composed array schemas, conditional schemas, ambiguous container type unions, tuple arrays, items: false, contains, additionalItems and unevaluatedItems also use JSON. Item defaults/examples initialize additions; required fields, uniqueness and item-count constraints remain the target API’s responsibility. Scalar roots and duplicate property names require the raw editor. Root array enums/constants also retain JSON mode. Object composition expansion also stops after 32 schema nodes or eight composition levels per container. These boundaries never truncate the request. OpenAPI 3.0 typed nullable fields and 3.1 null type unions keep their respective meanings.

Sensitive examples

For JSON bodies, displayed/copied snippets replace values marked writeOnly: true or format: password with YOUR_SENSITIVE_VALUE, including referenced schemas, nested objects, array items and composition branches. Known credentials are also scrubbed from decoded JSON strings, so Unicode escapes cannot bypass a direct string comparison. Pattern and conditional schema branches are handled conservatively; a value may be redacted even when a specific branch would not apply. The redactor does not execute spec-supplied regular expressions.

Invalid, duplicate-key, oversized, excessively complex or unresolved JSON bodies use YOUR_REQUEST_BODY in snippets when safe redaction cannot be established. Redaction changes only the displayed example; the actual request uses the body you edited. The raw JSON editor displays the actual values for review. Response bodies are not covered by request redaction.

Annotations and known credentials cannot identify every secret. Mark sensitive schema fields, review copied requests and avoid entering production credentials in demo sites. Logical form-urlencoded inputs use schema-aware JSON redaction before encoding; literal encoded-form snippets omit the body. Other non-JSON body formats rely on known-credential replacement. Schema-aware JSON redaction is not an XML/form-data parser.

Programmatic clients can pass { schema, schemas, openapiVersion } as the third argument to redactRequest, or call redactJsonBody directly. Generic request redaction without that context does not perform schema-aware body traversal. The public parseJsonValue, serializeJsonValue and setJsonProperty helpers in @davidniessen/doctopus-contracts preserve number tokens for integrations that build their own editors.

See form-urlencoded bodies, request serialization, OAuth authentication and generated snippets for the remaining request behavior.

For binary files with text or JSON parts, use the multipart editor. File selections stay separate from logical JSON values and generated source.