Swift-CBORLD

Development biography · earlier archive

Development profile compiled from project source and retained records in October 2026. Dates and test results describe those records; they do not imply a new build, live acceptance test or public release.

Intro

Swift-CBORLD is an independent, native Swift implementation of CBOR-LD, a compact binary encoding of JSON-LD linked data. It compresses JSON-LD documents into small CBOR byte strings using the vocabulary in their contexts, restores them exactly, and keeps the evidence for every compatibility claim inspectable. It has no third-party dependencies. It is not an official Digital Bazaar or W3C project.

Biography

Linked data is expressive but verbose: every JSON-LD document repeats long IRIs and term names that both sides already know from a shared context. CBOR-LD removes that repetition by replacing context-defined terms and typed values with small integers inside a CBOR envelope. Swift-CBORLD brings that transformation to Apple platforms and Linux as a native Swift 6 library, without wrapping a JavaScript runtime.

The project's first principle is compatibility as a measured result, not a promise. By default it reproduces the wire format of Digital Bazaar's JavaScript reference processor (cborld 8.1.x, pinned at commit 48bac5a), so existing byte fixtures do not move. Its interoperability evidence is retained in the repository: a 114/114 cross-decode snapshot across Swift, JavaScript, Python and Rust processors; 11 of 11 fixtures byte-identical with the LDC Labs Rust implementation; and immutable, SHA-256-pinned comparator archives that public CI re-verifies weekly.

Its second principle is that bytes should be reproducible on demand. Alongside the compatibility default it offers explicit RFC 8949 deterministic profiles (length-first and core deterministic), shortest-exact float widths and NaN normalisation. That makes CBOR-LD output suitable for content hashing, deduplication and signing in an enclosing protocol. A property test found that an early core-deterministic fast path ordered keys incorrectly; it was fixed before the first release and recorded in the changelog.

The third principle is bounded handling of untrusted input. Decoding presets (untrustedCompatible, untrustedDeterministic) cap input size at 16 MiB, nesting at 64 levels and container items at 65,536, and reject duplicate keys and indefinite lengths. Encoding limits stop output before it crosses a configured size. A context-loading policy bounds documents, bytes, import depth, redirects and term definitions per operation, with scheme, host and media-type allowlists. The core never fetches contexts from the network: every context comes from a registry or loader the application supplies, and can be pinned by fingerprint.

Integrity is deliberately separated from authentication. The package computes transport digests of exact bytes and domain-separated structural, context and dictionary fingerprints. It writes versioned integrity manifests as sidecars and produces per-check verification reports. It never claims that a digest proves who produced a document, or that a structural fingerprint proves RDF equivalence.

For the evolving W3C specification, Swift-CBORLD implements registry entries and processing models from the CBOR-LD 1.0 editor's draft, dated to w3c/cbor-ld revision 992f9335703c (2026-09-16). That covers semantic compression on or off; the built-in url, xsd-date, xsd-date-time and multibase codecs; user codecs whose output is decoded back and compared; and rejection of unknown codecs. Because the pinned reference processor predates processing models, this part is verified only by the package's own tests, and the project says so.

Beyond the core, it offers streaming validation and decoding with incremental digests; prepared sessions with a bounded context cache; and concurrent batch encoding and decoding with results streamed in completion or input order. A separate CBORLDCompute module defines versioned contracts for delegating bounded work (hashing, scans, key ordering, multibase, CDDL) to other backends. Its shadow-verifying provider checks every candidate result against a CPU reference and keeps CPU fallback distinct from accelerated execution in its receipts.

The newest addition is cborld, an offline command-line tool that encodes, decodes, inspects, digests and verifies CBOR-LD, reading contexts only from local files. It already has a first consumer: the ccx Claude+Codex console stores its workflow evidence packets as deterministic CBOR-LD pinned to its own context, at roughly 40% of the JSON size, as measured and reported by ccx.

Swift-CBORLD is a preview, built and maintained with AI-assisted engineering, and its documentation states its limits as plainly as its features. It is not a JSON-LD expansion or RDF canonicalisation engine, provides no signatures or certificate trust, and does not claim complete CBOR-LD 1.0 conformance while the specification remains an editor's draft.

Use Cases

• Linked-data encoding: compact transport and storage of verifiable credentials, activity streams and other JSON-LD vocabularies on Apple platforms and Linux.
• Evidence interchange: deterministic, pinned, manifest-checked records that another party or tool can verify byte for byte. ccx's workflow packets are a live example.
• Interop testing: a neutral lab with public fixtures, comparator pins and portable result schemas.

Features

• JavaScript-compatible CBOR-LD 1.0 by default, plus pre-1.0 range and legacy-singleton envelopes.
• Opt-in RFC 8949 length-first and core deterministic serialisation.
• Registry entries and processing models from the dated W3C editor's draft: built-in and user-supplied codecs, caller-provided type tables, provisional entries.
• Contexts loaded only from application-supplied sources, with fingerprint pins and a bounded loading policy.
• SHA-256/384/512 transport digests and domain-separated structural, context and dictionary fingerprints. On Apple platforms the hashing uses CryptoKit, with a portable Swift fallback that is tested for agreement.
• Integrity manifests (sidecars, never inside the envelope) and per-check verification reports.
• Untrusted-input presets, encoding limits, typed error codes with byte-offset diagnostics, and lossless CBOR inspection.
• Streaming validation and decoding of single documents, with incremental digests.
• Native Codable encoder and decoder for JSONValue.
• Prepared sessions with a bounded, expiring cache; concurrent batch encoding and decoding with results streamed in completion or input order.
• The CBORLDCompute module: 13 versioned compute-family contracts, CPU references, and shadow verification.
• The cborld CLI: encode, decode, inspect, digest, verify. Offline, with --context, --pin, --require-pins, --hex and manifests.

Workflow

• Pin the context: cborld digest --kind context ctx.jsonld
• Encode deterministically with a manifest: cborld encode rec.json --context URL=ctx.jsonld --pin URL=DIGEST --require-pins --mode length-first-deterministic -o rec.cborld --write-manifest rec.manifest.json
• Inspect without loading contexts: cborld inspect rec.cborld
• Verify on receipt: cborld verify rec.cborld --manifest rec.manifest.json --context URL=ctx.jsonld --require-pins --untrusted-deterministic --json

In Swift: CBORLDEncoder / CBORLDDecoder, CBORLDContextRegistry with expectedFingerprints, CBORLDDecodingConfiguration.untrustedDeterministic, CBORLD.integrityManifest and CBORLD.verificationReport.

Foundations

• Swift 6 with strict concurrency; no third-party dependencies.
• Platforms: macOS 13+, iOS/tvOS 16+, watchOS 9+, visionOS 1+, Linux. iOS, tvOS, watchOS and visionOS are build-verified only, not runtime-tested.
• Standards: CBOR (RFC 8949), JSON-LD contexts, and the CBOR-LD 1.0 editor's draft at w3c/cbor-ld 992f9335703c.
• Reference: Digital Bazaar cborld 8.1.x at commit 48bac5a, BSD-3-Clause, with notices retained.
• Licence: BSD-3-Clause.

Dated Maturity

• Status: source-first 0.1.0 preview, not yet tagged. The changelog's 0.1.0 entry is marked "Unreleased".
• CI: PR #1, which carries the review implementation, passed all 15 public CI checks on commit 2fffaa5. Those checks cover Swift 6.0 on macOS and Linux, Swift 6.4, an advisory nightly toolchain, the four Apple device builds, ASan, TSan, coverage, and evidence.
• Earlier public CI run 34752516586 (2026-09-13, commit af20539) passed 75 tests.
• The current suite is 164 tests, plus 10 for the CLI.
• Line coverage: CBORLD about 93.9%, CBORLDCompute about 93.0%, CBORLDCommandLine about 98.7%.
• PR #2 (the CLI) was still in CI at last check; its most recent fixes target coverage tooling, not CLI behaviour.
• Neither PR had merged at last check, and no GitHub release or Swift Package Index listing exists yet.

Roadmap

• Merge PR #1, then the stacked PR #2.
• Record the release commit's public CI run in Interop/STATUS.md and lab-status.json, then date the changelog.
• Signed 0.1.0 tag, GitHub prerelease, and Swift Package Index submission (.spi.yml is ready).
• Optional companion package swift-cborld-semanticcompute for accelerated families, only once SemanticCompute 1.23.0 is publicly resolvable and independently verified. It is not part of 0.1.0.
• Promotion to 1.0 only after the API, context-loader contract and compatibility promises are stable in real downstream use, and the W3C spec leaves editor's-draft status.

Limits

• Not a JSON-LD expansion, compaction, framing or RDF canonicalisation engine.
• No signatures, certificate trust, Merkle proofs or network context fetching. A manifest detects change but does not authenticate the producer.
• Processing-model behaviour has been checked only by the package's own tests.
• Compressed registry entries are not streamed, and constant-memory compression is not claimed.
• The 2.22x Swift-vs-Rust speedup is fixture-, machine- and toolchain-bound CPU evidence, and is not SemanticCompute evidence.
• Xcode 16 cannot build the whole package, because the cborld executable's name differs from the CBORLD module only in case. Building the library schemes works.

FAQ Q: Is it official? A: No. It is an independent implementation, not endorsed by Digital Bazaar or the W3C. Q: Will it change my existing CBOR-LD bytes? A: No. The default reproduces the JavaScript reference's bytes, and deterministic profiles are opt-in. Q: Does it fetch contexts from the internet? A: Never. You supply contexts, and can pin them by fingerprint. Q: Can a digest or manifest prove who wrote a document? A: No. It detects change; sign the transport digest in your own protocol to prove origin. Q: Is it safe for untrusted input? A: Use the untrusted presets, which bound size, depth and item counts and reject duplicate keys. The CI runs address and thread sanitizers and seeded property tests. Q: Is GPU acceleration included? A: No. Compute contracts are included with CPU references; any accelerator adapter would be a separate, optional package. Q: How do I install it? A: Through Swift Package Manager, from the 0.1.0 tag once it is published. Until then, use the main branch or a pinned commit.