RhoeJSON

RhoeJSON is the public Swift JSON engine for the RhoePlatform foundation line. It provides a strongly typed JSON value model, JSON5 parsing, JSONPath queries, JSON Pointer and JSON Patch mutation, schema validation, structured-format conversion, streaming support, binary codecs, a jq-inspired filter subset, a WASM facade, browser preview, and the rhoejson CLI.

This repository is currently staged as the Apache 2.0 public release candidate for 0.1.0. It is intentionally not initialized as a git repository yet. The active release-readiness roadmap is tracked in Documentation/Release/ReleaseReadinessRoadmap.md.

Repository Metadata

• Description: Swift-native JSON engine, CLI, browser preview, format conversion, streaming, binary codec, and WASM target for RhoePlatform.
• License: Apache 2.0.
• Primary language: Swift 6.2 with Swift Package Manager.
• CLI identity: rhoejson, with planned Homebrew aliases rhoejn and json.
• Public docs: GitHub Pages documentation is planned before public cutover.
• Optional Apple system API: JSONSchemaAIGenerator is compiled only on macOS when Apple's FoundationModels framework is available.
• Keywords: JSON, JSON5, JSONPath, JSON Pointer, JSON Patch, JSON Schema, Swift, CLI, WebAssembly, WASM, CBOR, MessagePack, Apache 2.0.

Quick Start

Add RhoeJSON to a Swift package after the first public tag is cut:

dependencies: [
    .package(url: "https://github.com/RhoePlatform/RhoeJSON.git", from: "0.1.0")
]

Use the engine from Swift:

import RhoeJSONKit

let value = try JSONValue(data: Data(#"{"name":"RhoeJSON"}"#.utf8))
print(value.prettyPrinted)

Build the CLI from source:

swift build -c release --product rhoejson
./.build/release/rhoejson --version

Query JSON with JSONPath:

rhoejson query data.json '$.records[*].name'

Use jq-shaped muscle memory for common filters:

rhoejson jq '.records[] | select(.active) | {id, name}' data.json
rhoejson jq '.records | map(.name)' data.json --compact
rhoejson jq '.records[] | .name' data.json --raw
rhoejson jq '.records | sort_by(.team, .score) | map({name, total: (.qty * .price)})' data.json
rhoejson jq '.records | map(if .score >= 95 then .name else empty end) | join(",")' data.json --raw
rhoejson jq '.records[0].score += 5 | del(.records[1].active)' data.json --compact
rhoejson jq '.records[].score += 1 | del(.records[].draft)' data.json --compact
rhoejson jq 'path(.records[].name), getpath(["meta", "source"])' data.json --compact
rhoejson jq 'reduce .records[] as $record (0; . + $record.score)' data.json --compact
rhoejson jq 'foreach .records[] as $record (0; . + $record.score; {name: $record.name, total: .})' data.json --compact
rhoejson jq '.records[0] as {name: $name, score: $score} | "\($name)=\($score)"' data.json --raw
rhoejson jq 'try (.records[].score | tonumber) catch empty' data.json --compact
rhoejson jq '[recurse | numbers]' nested.json --compact
rhoejson jq '[inputs]' --null-input shard-a.json shard-b.json --compact
rhoejson jq 'def active_name: select(.active) | .name; .records[] | active_name' data.json --raw
rhoejson jq 'def project(f): .records | map(f); project({name, passed: (.score >= 90)})' data.json --compact
rhoejson jq '"score=\(.records[].score)"' data.json --raw
rhoejson jq '"123abc456def" | gsub("[0-9]+"; "#")' --null-input --raw-output
rhoejson jq '"prefix-value" | ltrimstr("prefix-")' --null-input --raw-output
rhoejson jq '"Rhoe" | explode' --null-input --compact
rhoejson jq '.meta.missing // "fallback"' data.json --raw

The jq command intentionally implements a practical subset, not full jq compatibility. Supported features include ., .foo, .["key"], .[0], slices, .[], pipes, comma output, array/object construction, literals, arithmetic and boolean operators, // defaults, if ... then ... elif ... else ... end, lexical variables with as $name and $name, destructuring bindings such as as {name: $name} and as [$a, $b], no-argument def filters, filter-argument def name(f; g): ... functions, recursive user functions, try ... catch, while(condition; update), until(condition; update), recurse, walk(filter), reduce ... as $name (init; update), foreach ... as $name (init; update; extract), empty, type selectors, entry transforms, string predicates, map(...), map_values(...), select(...), has(...), sort_by(...), group_by(...), unique_by(...), min_by(...), max_by(...), 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(...), with_entries(...), path assignment (=), update assignment (|=), arithmetic assignment (+=, -=, *=, /=, %=), fallback assignment (//=), and collection builtins such as sort, unique, min, max, add, and reverse. Mutation supports field/index paths and .[] generator paths rooted at ..

Forward references between user-defined filters are supported as a RhoeJSON-inspired extension, but they are not labeled exact-compatible because jq rejects calls to functions defined later in the same program.

Supported jq-style CLI flags include -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, --tab, -e/--exit-status, and -f/--from-file for loading the filter program from a file. The command accepts multiple input paths and multiple whitespace-separated JSON texts, matching the common jq stream model. Variable binding supports jq's exact --arg name value and --argjson name JSON forms, plus --rawfile name path for binding UTF-8 file contents and --slurpfile name path for binding a file's JSON texts as an array. Positional argument binding supports jq's exact --args and --jsonargs forms through $ARGS.positional; use --args -- --flag-like when a positional string begins with -, matching jq's end-of-options marker. The staged --arg name=value, --argjson name=json, --rawfile name=path, and --slurpfile name=path conveniences remain accepted.

The jq compatibility roadmap and pinned subset conformance cases are documented in Documentation/Compatibility/JQCompatibilityRoadmap.md. Maintainers with jq installed can run:

bash Scripts/validate-jq-subset-conformance.sh

Format JSON with sorted keys:

rhoejson format data.json --sort-keys

Apply an RFC 6902 JSON Patch:

rhoejson patch data.json --patch patch.json

Preview a JSON document in the browser:

rhoejson preview data.json -o /demo

The preview command starts or reuses a local daemon at 127.0.0.1:38211, renders a dependency-free tree/detail HTML interface, watches the JSON source and optional schema file, and live-reloads the browser when either changes. On macOS, rhoejson-preview-menu is auto-launched by default as a menu-bar control surface. Use --no-menu or RHOEJSON_PREVIEW_MENU=0 for scripts.

Attach JSON Schema validation to the same live preview:

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

First-Wave Package Surface

The 0.1.0 public staging package exposes:

• RhoeJSONKit: core JSON value, parsing, JSON5, JSONPath, Pointer/Patch, schema, formatting, streaming, and structured-output APIs.
• JSONSchemaAIGenerator: optional macOS-only Apple Foundation Models system API for local schema-conforming JSON example generation. It is not compiled on Linux, WASM, or Linux Homebrew bottle surfaces.
• RhoeJSONFormatKit: CSV, Markdown, TOML, XML, and YAML conversion helpers.
• RhoeJSONBinaryCodec: BinaryJSON, CBOR, and MessagePack codecs.
• RhoeJSONFilter: jq-inspired filter parser and evaluator for command-line inspection and lightweight transformations.
• RhoeJSONCLIEngine: reusable CLI core for query, format, validate, convert, jq-shaped filters, patch, and stream workflows.
• RhoeJSONPreview: local preview daemon, control client, watched route registry, and browser renderer.
• RhoeJSONWasm: WebAssembly-friendly validation, formatting, query, and patch facade.
• rhoejson: public command-line tool.
• rhoejson-preview-menu: macOS menu-bar companion for watched preview files.

Deferred From 0.1.0

The first public release deliberately stays focused on the JSON engine and CLI. The following surfaces are out of scope until they have separate contributor boundaries:

• platform orchestration, workflow-pipeline graphs, and starter artifact generation.
• MCP host/runtime/publication surfaces.
• AI connectors, OpenAPI connector substrate, workflow orchestration, and vector index APIs. The optional macOS Apple Foundation Models wrapper is documented separately as a local Apple system API, not a connector surface.
• SwiftUI/UI kit, Transferable import/export, Studio apps, and application product surfaces.

Maintainer Gates

Current release-readiness checks:

Scripts/validate-public-hygiene.sh
swift package dump-package
swift build --product rhoejson
swift build --target RhoeJSONCLIEngine
swift build --target RhoeJSONFilter
swift build --target RhoeJSONPreview
swift build --target RhoeJSONWasm
swift build --product rhoejson-preview-menu
swift test
bash Scripts/CI/validate-docs.sh
bash Scripts/CI/validate-examples.sh
bash Scripts/CI/validate-cli-artifacts.sh
bash Scripts/CI/validate-homebrew-template.sh
bash Scripts/verify-cutover.sh

The umbrella local release gate is:

bash Scripts/CI/verify-release-readiness.sh

Linux build checks, WASM SDK checks, source archive checksums, and bottle publication remain final cutover gates after the private remote and tag exist.

Release Strategy

• Public release strategy: Documentation/Release/PublicReleaseStrategy.md
• Staging status: Documentation/Release/PublicStagingStatus.md
• Release readiness roadmap: Documentation/Release/ReleaseReadinessRoadmap.md
• Apple Foundation Models boundary: Documentation/Platform/AppleFoundationModels.md

Do not run git init, create the new GitHub repository, tag v0.1.0, or switch visibility to public until the staging folder passes the full preflight audit.