Mochi Core Spec

The language-agnostic specification for a Mochi core client — the batching, non-blocking HTTP client that every Mochi SDK is built on. This repo is the single source of truth for how a core behaves, so that mochi-js, mochi-py, and future cores (mochi-go, mochi-jvm, mochi-rust, …) stay consistent.

A Mochi SDK in any language is two layers:

┌─────────────────────────────┐
│  library adapter            │  discord.js / discord.py / DiscordGo / JDA …
│  (maps events → track())    │
├─────────────────────────────┤
│  core client  ◀── this spec │  batching, retries, wire format, snapshots
└─────────────────────────────┘
              │ HTTP
              ▼
      Mochi ingest + snapshot API

This repo does not contain an implementation. Each language ships its own core (in mochi-js, mochi-py, …) that MUST conform to SPEC.md and pass the shared vectors in conformance/.

Contents

• SPEC.md — normative specification (RFC 2119 keywords).
• schema/ — JSON Schema (draft 2020-12) for the wire types: event, snapshot, and the ingest-request batch wrapper. These make the wire format machine-checkable in any language.
• conformance/vectors.json — language-neutral test vectors: wire serialization, the retry-backoff schedule, and valid/invalid documents for the schemas. Every core's test suite SHOULD load these and assert against them.

Validating

The schemas and every vector are checked together — any JSON Schema draft-2020-12 validator works. The wire schemas cross-reference by filename (ingest-request $refs event.schema.json), so load all three into one registry before validating. conformance/vectors.json carries the schemaValidation cases: each valid doc MUST pass its schema and each invalid doc MUST fail.

Reference implementations

The two existing cores are the reference for this spec; where the spec and a reference disagree, the spec is authoritative and the reference is a bug.

• JavaScript/TypeScript — @mochi-analytics/core (mochi-js)
• Python — mochi-analytics (mochi-py)

Versioning

The spec is versioned independently of any SDK. Breaking wire or behavior changes bump the major version. A core declares which spec version it targets in its README.

Community

Questions about the spec or building a new core? Join the Mochi Discord.

License

Apache-2.0.