# Mapping

URL: /business/nouns/mapping · Id: `noun:mapping`

> A Mapping translates one Source’s shape into the registry’s: its fields to a Noun’s fields, or an outside endpoint’s inputs and outputs to a Verb’s.

A Mapping translates one [Source](/business/nouns/source)’s shape into the registry’s: its fields to a [Noun](/business/nouns/noun)’s fields, or an outside endpoint’s inputs and outputs to a [Verb](/business/nouns/verb)’s.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `verb` | `string` | No | The Verb it serves, such as `Meeting.book`; a Verb has many Mappings, ranked. |
| `fields` | `json` | No | Each outside field or event and the Noun property or Event it maps to. |
| `direction` | `string` | No | `both` still keeps db.sb the record; the outside tool never becomes a second one. |
| `convert` | `text` | No | How a value changes on the way, such as cents to money or a picklist to closed values. |
| `rank` | `integer` | No | Order tried when the preferred Mapping fails or finds nothing; the Policy orders it by cost per accepted result. |
| `preferred` | `boolean` | No | True for the Mapping a Verb tries first. |
| `door` | `string` | No | How the outside endpoint is classed; an unclassed write is one-way and waits its delay window. |

## Object
```json
{
  "$id": "https://api.sb/petpantry.shop/mappings/mapping_1",
  "$type": "Mapping",
  "verb": "Meeting.book",
  "fields": {},
  "direction": "in",
  "convert": "Cents to money",
  "rank": 1,
  "preferred": true,
  "door": "oneWay"
}
```

## Relationships
- <a id="rel-translates"></a>A Mapping **translates** one [Source](/business/nouns/source): a [Source](/business/nouns/source) reaches the registry’s [Nouns](/business/nouns/noun) and [Verbs](/business/nouns/verb) through its Mappings, one per Verb it serves. `translates`, inverse [`mappings`](/business/nouns/source#rel-mappings).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| <a id="create"></a>[Mapping.create](/business/nouns/mapping/create) | Creates a Mapping. Inherited from [Noun](/business/nouns/noun). | None. | `Mapping.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Mapping.get](/business/nouns/mapping/get) | Returns one Mapping by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Mapping.list](/business/nouns/mapping/list) | Returns Mappings, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Mapping.update](/business/nouns/mapping/update) | Changes the given properties of a Mapping. Inherited from [Noun](/business/nouns/noun). | None. | `Mapping.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Mapping.delete](/business/nouns/mapping/delete) | Deletes a Mapping; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Mapping.deleted` | One-way: `send`, `do` |

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Mapping.create` | Yes | Yes | Yes | No |
| `Mapping.get` | Yes | Yes | Yes | Yes |
| `Mapping.list` | Yes | Yes | Yes | Yes |
| `Mapping.update` | Yes | Yes | Yes | No |
| `Mapping.delete` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Add a mapping to Kiln Bakery.
```

**API**

```bash
curl -X POST https://api.sb/kilnbakery.com/mappings \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"verb":"Meeting.book"}'
```

```json
{
  "api": "https://api.sb/kilnbakery.com",
  "mapping": {
    "$id": "https://api.sb/kilnbakery.com/mappings/mapping_1",
    "$type": "Mapping",
    "verb": "Meeting.book",
    "fields": {}
  },
  "action": {
    "$id": "https://api.sb/kilnbakery.com/actions/action_1",
    "operation": "Mapping.create",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/kilnbakery.com/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const mapping = await $.Mapping.create({ verb: 'Meeting.book' })
```

**CLI**

```bash
npx startup-builder do Mapping.create --json '{"verb":"Meeting.book"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Mapping.create({ verb: 'Meeting.book' })"
  }
}
```

## Example
A [Startup](/business/nouns/startup) books [Meetings](/business/nouns/meeting) through an outside calendar tool. One Mapping turns the tool's `start_time` into the Meeting's `at`, and a second, lower-ranked Mapping takes over when the first finds no slot.