# Data rights and audiences

Whose data it is, the name readers see beside it, its terms and whether Kanboombo may keep it; and who may read your plug-in. One holder per plug-in.

Every record belonged to someone before it reached your readers. `licence`
says who, and what Kanboombo may do with it; `audience`, who may read it. Both
are in the [digest](/developers/plugins/publish/updates/#digest) a person
approves.

## The licence block

```json norun="a fragment of plugins/harbour-almanac/plugin.json"
"licence": { "holder": "Kanboombo (invented example data)", "attribution": "Harbour Almanac", "terms": "https://kanboombo.com/developers/plugins/examples/harbour-almanac/", "retain": "yes" }
```

| Field | What you write | What it does |
|---|---|---|
| `holder` | Who publishes the data, in full: `Banco Central de la República Dominicana`. Up to 200 characters. | Names the holder. Readers see it beside your records when you give no `attribution`. |
| `attribution` | The short name readers know it by: `Banco Central`. Up to 40 characters. Optional. | Shown beside your records on every reader's days. |
| `terms` | A link to the terms the data is published under, or `null` when there are none to link. Up to 500 characters. | Tells the person who reviews your plug-in, and later your readers, where the terms are. |
| `retain` | `yes`, `no` or `unknown`: whether Kanboombo may keep the records. | Decides whether the records may ever be purged. |

An incomplete block fails with
[PLG-MANIFEST-LICENCE](/developers/plugins/publish/submission-errors/#plg-manifest-licence).

## retain: may Kanboombo keep the records? {#retain}

Kanboombo keeps what your plug-in writes, keeps every revision beside the value
it replaced, and never resets them. Records stay when a reader turns your
plug-in off and when a plug-in is removed. Only a purge removes them, and a
purge is offered only when the licence says the records may not be kept.

| Value | It means | What Kanboombo does |
|---|---|---|
| `yes` | The terms let Kanboombo store the records and keep them. | Keeps every record and every revision. |
| `unknown` | Nobody has settled it yet. | Keeps them, and does not offer a purge. A person reads the terms and records the answer. |
| `no` | The terms do not let Kanboombo keep the records for good. | Keeps them for now, and offers a purge at host.kanboombo.com. |

### The purge {#purge}

A purge is offered at host.kanboombo.com › Plug-ins only while the answer the
Server holds for your plug-in is `no`:

1. It runs as a dry run first: it counts the records and revisions it would
   remove, and removes nothing.
2. To remove them, the person types your plug-in's id.
3. It removes the records and their revisions in one transaction. It cannot be
   undone.
4. The runs stay. They are the record of what ran on the Server, and they hold
   versions, digests, counts, sources and errors, not the records.

The Server records your manifest's `retain` the first time it registers your
plug-in. After that, the answer it acts on is the one a person records at
host.kanboombo.com › Plug-ins, once they have read the terms: today a later
version's manifest does not change it by itself. Say what you know, and say
`unknown` when you do not know.

## One holder, and open licences

One licence means one holder's data: the right name on every record, one set of
terms and one `retain` for all of it, and a purge that removes no one else's
records. Two publishers are two plug-ins; your own data makes you the holder.

An open licence settles these questions in advance: the
[ODbL 1.0](https://opendatacommons.org/licenses/odbl/1-0/), for example, lets
anyone keep, share and show the data if they say where it comes from and share
an adapted copy of the database under the same licence. Attribution is then the
holder's name beside every record and a way to find the terms. Read the licence
itself, not a summary, and link the exact version the holder names.

Say what is known, then widen it. DOP Economy began `"terms": null`,
`"retain": "unknown"` and `private`; once the Banco Central's ODbL publication
of the same rate was recorded as the basis, version 1.1.0 linked the ODbL, said
`yes` and became `public`.

## When the terms are unclear {#unclear}

Ask the holder in writing, before you build: what you will download and how
often, that Kanboombo keeps the records and shows them with their name, and
whether that is allowed, under which terms. Downloads announce themselves as
`Kanboombo plug-ins (+https://kanboombo.com)`. Keep the answer for
[review](/developers/plugins/publish/review-requirements/#source-terms). Until
then, `"terms": null`, `"retain": "unknown"` and `private` are the honest ones.

## Audiences {#audiences}

| `audience` | Who may read it | Where it runs |
|---|---|---|
| `public` | Anyone signed in, and a Mac's local API, which is served public plug-ins only | On the Server |
| `private` | Up to 500 people by account email and 100 organizations, set at host.kanboombo.com | On the Server |
| `local` | You, on your Mac | Your Mac only: the Server refuses to approve it |

Choose `public` only when the terms let everyone see the data with attribution;
until you are sure, `private`. A private plug-in reaches an organization's
active members, never its guests or people who have left, keeping a licensed
source inside the people its licence covers; it is never served to a Mac's
local API, and anyone not on the list is told it does not exist.

### local {#local}

Choose a folder in Settings › Developer Mode › **A plug-in folder on your
days**, and Kanboombo on your Mac runs it for the days on your screen, marked
"On this Mac · not published". Its records are never stored and never sent: not
to Kanboombo, not to an organization, not anywhere. Any plug-in's folder shows
this way before review: that is how you see your own work
([On your own days](/developers/plugins/reference/cli/#on-your-days)).

### Turning a plug-in on {#turning-a-plug-in-on}

May read is not sees: nothing is pushed onto anyone's days. A reader turns a
plug-in on under Show sections in any day's "…" menu (the synced preference
`plugins.<id>.shown`: `true`, `false`, or `null` for no choice). An owner or
admin can turn it on for members who made no choice ("On for … members"); a
member's own choice wins, and a Mac's local API applies only your own. In the
store, `kanboombo://plugins`, you install for yourself and an owner or admin for
members (who stay removed if they remove it); a public plug-in is installed by
no one until they ask. Hiding or removing a plug-in keeps its records.