Skip to content

docs: document strict JSON consumer validation with Node #345

Description

@codeforester

Goal

Show downstream CLI authors how to verify that base-cli JSON and NDJSON output is accepted by a strict cross-language parser.

Background

Python's JSON loader accepts some non-standard numeric tokens by default. The public contract is intended for consumers such as Node JSON.parse, so the validation boundary should be visible to newcomers.

Scope

  • Add a focused documentation example using Node's built-in JSON.parse or the repository's existing contract validator.
  • Explain the difference between one JSON envelope and newline-delimited records.
  • Point to the canonical output and JSON contract references.
  • Include the expected failure shape for invalid output without embedding a real secret or private path.

Acceptance criteria

  • The example uses a strict parser rather than only Python round-trip loading.
  • It explains how a consumer should handle parse failure.
  • It links to the existing contract fixture or validator.
  • It does not redefine the public serialization contract.
  • A contributor can validate the example without private infrastructure.

Validation

  • Run the documented Node command or existing contract validator.
  • Run git diff --check.
  • Verify all internal links.

Non-goals

  • Do not change serializer behavior.
  • Do not add a new parser dependency.
  • Do not use a secret-shaped fixture in the repository.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

area: docsDocumentation and public guidance ownership.documentationDocumentation improvementsgood first issueGood for newcomershelp wantedExtra attention is needed

Type

No type

Projects

  • Status
    Done

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions