RhoeJSON Public Release Strategy

Status: Phase 25 Sprint 4 QA hardening Target repository: RhoePlatform/RhoeJSON Target release: 0.1.0 License: Apache 2.0

RhoeJSON is the public Swift JSON engine in the RhoePlatform foundation line. The first release should feel complete for contributors who want a JSON library, CLI, browser preview, and WASM-friendly facade, while staying deliberately narrow enough to maintain a clean public boundary.

Release Positioning

The 0.1.0 release is an engine-first release, not a broad platform release. It should give users a practical JSON toolchain:

• parse, inspect, query, format, validate, convert, patch, and stream JSON.
• work with JSON5, JSONPath, JSON Pointer, JSON Patch, JSON Schema, CBOR,

MessagePack, and structured-format conversions.

• run rhoejson locally as a polished CLI with predictable help, errors,

jq-inspired filters, and examples.

• preview JSON documents in a browser with a lightweight tree/detail interface.
• consume a WASM-friendly API surface for validation, formatting, querying, and

patching.

• use the optional macOS-only Apple Foundation Models system API for local

schema-conforming JSON example generation when Apple's framework is available.

Public Package Surface

The first public wave includes:

• RhoeJSONKit: core values, parsing, formatting, JSONPath, Pointer/Patch,

schema, diagnostics, streaming, and structured-output helpers.

• JSONSchemaAIGenerator: optional macOS-only Apple Foundation Models system

API guarded by os(macOS) && canImport(FoundationModels). It is not compiled into Linux CI, Linux packages, or WASM surfaces.

• RhoeJSONFormatKit: CSV, Markdown, TOML, XML, and YAML conversion helpers.
• RhoeJSONBinaryCodec: BinaryJSON, CBOR, and MessagePack codecs.
• RhoeJSONFilter: jq-inspired filter parser and evaluator for common CLI

inspection and lightweight transformations.

• RhoeJSONCLIEngine: reusable command execution core for the CLI.
• RhoeJSONPreview: preview daemon, route registry, control client, HTML

renderer, and watched-source support.

• RhoeJSONWasm: WebAssembly-oriented facade.
• rhoejson: primary public CLI executable.
• rhoejson-preview-menu: macOS menu-bar companion for the preview daemon.

The primary CLI identity is rhoejson. Homebrew aliases are planned as rhoejn and json.

Deferred Surface

The following areas stay outside 0.1.0 until they have explicit public contracts:

• platform orchestration and workflow-pipeline graph surfaces.
• starter artifact generation beyond simple examples.
• MCP host/runtime/publication surfaces.
• AI connector integrations and OpenAPI connector substrate. The optional Apple

Foundation Models wrapper is treated as a local Apple system API, not a connector or platform orchestration surface.

• vector index APIs and downstream search workflows.
• SwiftUI/UI kit, Transferable import/export, Studio apps, and application

product surfaces.

• product-specific fixtures, launch plans, or downstream application docs.

CLI Strategy

The CLI should be familiar to users of tools such as jq and jj, without claiming language compatibility with either. The public command families are:

• query: evaluate JSONPath-style expressions.
• jq: evaluate a jq-inspired filter subset for command-line muscle memory.
• format: pretty-print, compact, sort keys, or normalize input.
• validate: validate JSON syntax and optional JSON Schema constraints.
• convert: convert between JSON and supported structured formats.
• patch: apply RFC 6902-style JSON Patch documents.
• stream: process newline-delimited or event-stream JSON inputs.
• preview: start or reuse the local browser preview daemon.

The preview command is the interactive entry point:

rhoejson preview data.json -o /demo
rhoejson preview data.json --schema schema.json --route /validated --no-open

On macOS, rhoejson preview may launch rhoejson-preview-menu by default. Linux remains CLI-only.

The jq command supports the practical subset needed for common inspection and projection tasks:

• identity: .
• object and array selection: .foo, .["key"], .[0], .[-1], slices, and

.[]

• composition: | and ,
• constructors: [ ... ] and {key: .path}
• literals and operators: strings, numbers including exponent notation,

booleans, null, +, -, *, /, %, and, or, not, and //

• conditionals: if ... then ... elif ... else ... end
• lexical flow: expr as $name | ..., destructuring as {key: $value} and

as [$a, $b], $name, no-argument def filters, filter-argument def name(f; g): ... functions, recursive user-defined functions, try ... catch, while(condition; update), until(condition; update), recurse, walk(filter), reduce stream as $name (initial; update), and foreach stream as $name (initial; update; extract)

• selectors and flow: empty, arrays, objects, iterables, strings,

numbers, booleans, nulls, values, and scalars

• functions and builtins: map(...), map_values(...), select(...),

has(...), length, keys, keys_unsorted, type, sort, sort_by(...), unique, unique_by(...), group_by(...), min, max, min_by(...), max_by(...), add, reverse, to_entries, from_entries, contains(...), startswith(...), endswith(...), test(...), range(...), flatten, flatten(depth), first, last, nth(...), any, all, any(...), all(...), join(...), split(...), indices(...), index(...), rindex(...), tostring, tonumber, ascii_downcase, ascii_upcase, ltrimstr(...), rtrimstr(...), explode, implode, path(...), paths, paths(predicate), leaf_paths, getpath(...), setpath(path; value), test(...), match(...), capture(...), scan(...), sub(...), gsub(...), jq-style string interpolation with "\(...)", input, inputs, format encoders @text, @json, @html, @uri, @csv, @tsv, @sh, @base64, and @base64d, deterministic math helpers abs, floor, ceil, round, sqrt, sin, cos, tan, log, and exp, error(...), halt, halt_error(...), del(...), delpaths(...), and with_entries(...)

• path and generator mutation: =, |=, +=, -=, *=, /=, %=, and

//= for field/index paths and .[] generator paths rooted at .

• jq-style CLI flags: -n/--null-input, -R/--raw-input,

-s/--slurp, -r/--raw-output, --raw-output0, -j/--join-output, -a/--ascii-output, -c/--compact-output, -S/--sort-keys, --indent, and --tab, plus -e/--exit-status and -f/--from-file, with multiple input paths and multiple JSON texts

• jq-compatible variable flags: --arg name value and

--argjson name JSON, --rawfile name path, --slurpfile name path, plus --args / --jsonargs positional arguments through $ARGS.positional and staged name=value conveniences

Forward references between user-defined filters are available as a RhoeJSON-inspired extension, but they are not exact jq-compatible. Full jq language compatibility is deferred. Modules, label/break, broader regex replacement streams, Unicode normalization edge-case documentation beyond scalar code point conversion, jq streaming semantics, date/time, and environment or side-effect builtins such as env, $ENV, debug, and stderr are not part of 0.1.0. Raw environment exposure is deliberately deferred because public CLI environments frequently contain secrets. The staged compatibility roadmap is tracked in Documentation/Compatibility/JQCompatibilityRoadmap.md, with pinned subset cases under Tests/RhoeJSONFilterTests/Fixtures/jq-conformance/.

Preview Strategy

The preview server should remain dependency-free on the browser side. The HTML surface should provide:

• tree/detail navigation.
• pretty and raw JSON views.
• syntax highlighting.
• search.
• copy actions for JSONPath and JSON Pointer references.
• watched reloads for the JSON source and optional schema file.
• route lifecycle control through the preview daemon.

The daemon control API is intentionally local and narrow. It is not a general HTTP API server for the engine.

Documentation Strategy

The public repo should include:

• README quick start and command examples.
• API documentation for public Swift modules.
• CLI manual and shell completions.
• examples gallery with source files, run scripts, and canonical outputs.
• release, governance, security, and contributor docs.
• public staging status and release strategy documents.
• Apple Foundation Models platform-boundary documentation.

Documentation should describe what the release supports today and mark deferred features explicitly. It must not require users to know the history of the staging process.

Release Gates

The staging folder remains source-only until these gates pass:

• public hygiene scan.
• SwiftPM package dump.
• debug and release builds for the public CLI.
• target builds for CLI engine, preview, and WASM facade.
• target build for the jq-inspired filter engine.
• product build for the macOS preview menu on macOS.
• full Swift Testing suite.
• CLI smoke tests for --version, --help, and preview --help.
• jq-inspired filter smoke test.
• pinned jq subset conformance check when a local jq binary is available.
• preview menu --status-json smoke test.
• docs generation and artifact verification.
• examples render-all validation.
• Homebrew formula and bottle-template validation.
• Linux and WASM SDK checks where toolchains are available.

Platform Boundary

The JSONSchemaAIGenerator source file must remain guarded by:

#if os(macOS) && canImport(FoundationModels)

This keeps the API available to macOS developers with Apple Intelligence support while preventing Linux CI and Linux package artifacts from compiling or exposing Apple-only symbols.

Only after these gates pass should the public repository be initialized, committed once, pushed privately, enabled for CI and Pages, and then switched public after the final audit.