On this page
What belongs where
Open Music Collection is meant to grow by many hands: apps, homes and sources adding what they need without waiting for each other. That works only if everyone puts the same thing in the same place. So every property, endpoint or behaviour goes in exactly one of six places, and each place has one question.
| Place | The question | Examples |
|---|---|---|
| Not in the collection | Would the person miss it if the app or home disappeared? If not, it stays out | An app's caches and embeddings, can, a list's version, cursors, connections, changes not yet sent to a platform |
| The core | Does any music app need it to show, find, match or move a collection? Do two independent apps or sources already have it? Does it mean one thing? | Items, copies, sources, lists, entries, note, composers, folders, filter, color on lists, audio_hash, the rules for combining collections |
| A module | Do some apps share a vocabulary or protocol for it, without every app needing it? | Access (the protocol), DJ (cues, grids, analysis), Feeds, Share, Collector, Catalog and Commerce, Folder; a future Credits module |
| The home's choice | Could two homes choose differently, and apps still work with both? Then the specification says MAY, and the home says which in /me | Limits and budgets, which modules it supports, holding what unknown senders send, which app owns a namespace, webhooks, rate limits |
The home's namespace (com.example.home) | Does only this home need it, to restore its own state when the collection comes back? | Which tracks and lists the person hid, the home's own kinds of list (a Rekordbox My Tag), which lists are a source's colours |
| The home's own product, outside OMC | Is it a feature of one home? Then no OMC app may need it | Its own interface for held items, downloads, capture from links, devices, its own API and dashboard, personal tokens |
Ask the questions in that order. Most things stop at the first: an app's cache is not the person's data, however useful. Something that passes the core's three tests but only some apps use is a module. Something every home must do the same way for apps to work is the specification's; if homes may differ, it is theirs to choose and announce.
How things move
A property starts where its first user needs it: in an app's own namespace, or a home's. When a second app wants to read it, it becomes an OMC proposal for a module. When any music app would need it, it moves to the core in a minor version. Readers keep what they don't know, so nothing breaks on the way. The core's guide, Where a property goes, says the same for a single field.
A home must not keep something in its namespace that a second home would also need. That belongs in a proposal, so the next home doesn't invent its own.
Homes are examples, not owners
The specifications name no vendor in their rules. A home appears in them only as an
implementation, and its namespace in examples is com.example.home. The first home, Tangle
(namespace music.tangle), follows the same rules as any other:
- Its own apps and demos are ordinary OMC apps, with no privileges, using Access and what they know about platforms.
- It passes the reference validator's live check, and its documentation marks every feature that is its own.
- Anything it exports in its namespace is something only it needs.