JSON Schemas
Published JSON Schemas for the Toy format and every platform contract.
Schemas are served by the API at their $id URLs and copied here for offline reading. The Toy document schema is the portable format every host validates.
| Schema | Description | Files |
|---|---|---|
| Toy document | The portable Toy source format. | toy.schema.json · on tune.toys |
| ApiError | Error envelope returned by every failing API response. `requestId` echoes the X-Request-Id response header. | api-error.schema.json |
| ApiKeyScopes | Scopes granted to one developer API key. | api-key-scopes.schema.json |
| ApiKey | Metadata of one developer API key. The secret is returned once at creation or rotation and never stored in plain text. | api-key.schema.json |
| ApiUsage | Metered usage of one developer app in UTC hourly or daily windows. Counters are informational and may lag by up to 30 seconds. | api-usage.schema.json |
| ArtifactDescriptor | One registered build output of a product version. digest, size, inventory, targetProfile, format and arch never change; a correction is a new artifact. | artifact.schema.json |
| PlatformCommon | Shared scalar formats referenced by the other platform contracts. | common.schema.json |
| DeveloperApp | A developer app groups API keys, usage, webhooks and a tier. `tier` is the last observed effective tier, computed from the owner's feature:api.pro grant. | developer-app.schema.json |
| PlatformEnums | Closed platform enums. Generated TypeScript exports each as a type and an as-const array; this file is their single source. | enums.schema.json |
| LicenseCertificate | Offline license certificate payload (tunetoys.license-certificate/1), signed in a SignedEnvelope with the license key. Contains no device ID, email or handle. allowedMajor or until is absent for the all update policy. | license-certificate.schema.json |
| ListingRevisionContent | Content of one product listing revision. The effective value of a field is overrides[field] ?? generated[field]. | listing-revision.schema.json |
| SoundAnalysis | One engine run over a media version: its state, the facet summary the index reads and the full report. A newer engine version appends a row; the resolved view takes the newest ready one. | media-analysis.schema.json |
| SoundItem | The mutable catalog entry of one upload: what people see and edit (title, artwork, tags, declared musical fields, visibility). Bytes and rights live on its versions. Server-owned counters and the resolved view are separate shapes here. | media-item.schema.json |
| SoundRelation | A directional relation between two media items, created by either owner. Symmetric in the UI; a relation to an item the viewer cannot read is omitted. | media-relation.schema.json |
| SoundRendition | One derived artifact of a media version (peaks, preview, thumbnail, score page, piano roll, beats). Immutable; unique per version, kind, recipe, toolchain and profile. | media-rendition.schema.json |
| SoundVersion | One immutable upload of a media item: bytes, digest, rights, what the probe found and the tags the file carried. Never edited after creation; releases pin versions. | media-version.schema.json |
| MediaVocabulary | The closed vocabularies of the Sounds catalog as one document (served to editors and used as the zero-shot tag prompts). The long lists (`Instrument`, `Genre`, `Mood`) are defined here; the short ones reference enums.schema.json. Generated TypeScript exports each titled list as a type and an as-const array. | media-vocabulary.schema.json |
| NotificationEvent | Input of the single notify helper. params holds ICU arguments (ids, counts, handles), never rendered strings or private content. | notification-event.schema.json |
| PlatformMatrix | Per-version platform matrix: one entry per target profile. included means an artifact exists, supported is a creator claim, tested requires evidence. | platform-matrix.schema.json |
| PostContent | Author-supplied content of a review, comment or reply. Server-owned fields (author, verified owner, root, depth, pins, state) are not part of it. Replies inherit subject and team scope from their root. | post.schema.json |
| ProductPage | Visibility-filtered public product listing, documents, versions, offers and head metadata shared by HTML and React. | product-page.schema.json |
| SignedEnvelope | Ed25519 envelope for update manifests and license certificates. The signature covers a purpose-specific domain prefix followed by the exact payload bytes; verifiers check it before parsing and never re-canonicalize. | signed-envelope.schema.json |
| SoundLandingPage | Validated sound facet landing content, filters, pagination metadata and related categories. | sound-landing-page.schema.json |
| SoundSearchParams | Query of GET /v1/sounds and /v1/sounds/facets: every filter optional, bounded, and owned by the page URL. Facet counts answer for the same filter set. | sound-search.schema.json |
| StorefrontPage | Published or member-preview storefront sections, theme and public product cards. | storefront-page.schema.json |
| StorefrontRevisionContent | Content of one publisher storefront revision: validated theme tokens and ordered typed sections. Storefronts are data, never code. | storefront-revision.schema.json |
| UpdateManifest | Signed update feed payload for one product and channel (tunetoys.update-manifest/1). Lists artifact digests, never URLs or tickets. Signed in a SignedEnvelope with the update_feed key. | update-manifest.schema.json |
| Webhook | A pro-tier webhook endpoint. Deliveries are signed with TuneToys-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + "." + body)>. | webhook.schema.json |
The index of every schema is at tune.toys/schemas/index.json.