---
title: "Fields and type words"
url: https://services.dev/docs/service/fields
captured: [legal-walk.txt, tax-check.txt]
codes: [input_invalid]
---
# Fields and type words

URL: https://services.dev/docs/service/fields

> input and output name each field with one of eleven type words. Add ? for optional, [] for a list, and a note an agent can try.

## Smallest form

```ts
  input: { document: 'file', to: 'language: a BCP 47 tag, such as fr-CA' },
  output: { document: 'file' },
```

## Every form

| Word | In your code | On the wire | |
|---|---|---|---|
| `text` | `string` | `string` |  |
| `file` | `InFile` | `FileRef` |  |
| `url` | `string` | `string` |  |
| `email` | `string` | `string` |  |
| `number` | `number` | `number` |  |
| `money` | `number` | `number` | dollars in code and integer cents on the wire |
| `boolean` | `boolean` | `boolean` |  |
| `date` | `string` | `string` |  |
| `language` | `string` | `string` | a BCP 47 tag |
| `jurisdiction` | `string` | `string` | an ISO 3166 code (`US`, `US-TX`) |
| `party` | `Party` | `Party` | a person or organization outside the brand |

A type word, `?` optional, `[]` a list, `'word: a note, such as an example'`, a list of choices, or a schema.

| Written | Means |
|---|---|
| `'text'` | a required field, by its type word |
| `'text?'` | optional |
| `'text[]'` | a list |
| `'text: a note, such as an example'` | a note for the Site and the tool description; a "such as" lets an agent try it |
| `['plain', 'playful']` | one of these choices |
| a Standard Schema | Zod, Valibot or ArkType, with its JSON Schema in the manifest |

Order options: `max_usd`, `key`, `approved`, `metadata`. Every order carries these, so no input may take their names; `policy` too, once the Service declares one.

## A party, someone outside the brand

| Field | Type | |
|---|---|---|
| `name` | `string` | required |
| `email` | `string` | required: where the party's own links go |
| `org` | `string` | optional |

| A party field is read by | How |
|---|---|
| [an ask](https://services.dev/docs/service/ask.md) | `ask: '<field>'`: that party acts through their own link, with no account |
| [a Pool's conflict check](https://services.dev/docs/people/pool.md) | `clear.check` names the party fields a member clears before the packet opens |
| `party?` and `party[]` | optional, or a list; an ask with `all: true` waits for every party in the list |

## Seven surfaces

| Op | API | CLI | MCP | SDK | Site | Docs | App |
|---|---|---|---|---|---|---|---|
| `service.order` | `POST /jobs`, `POST /:service` | `<service> k=v …` | `order_<service>` | `<service>.order()` | `/<service>`: the order form | 10 error pages | customer portal |
| `service.quote` | `GET /:service.json` |  |  |  | `/<service>`: the price sentence | 1 error page |  |

[Operations](https://services.dev/docs/reference/operations.md) has every column of every row.

## Refusals

| Code | Category | HTTP | Why |
|---|---|---|---|
| [`input_invalid`](https://services.dev/docs/reference/errors.md#input_invalid) | invalid_request | 422 | The order doesn't match the Service's input. |

| Written | What TypeScript says |
|---|---|
| `input: { key: 'text' }, output: { document: 'file' }, price: 49` | `Type '"text"' is not assignable to type '"✗ key is an order option; rename this input"'.` |
| `const order: import('../src/index.ts').Data<{ client: 'party' }> = { client: { name: 'Ada Lovelace' } }` | `Property 'email' is missing in type '{ name: string; }' but required in type 'Party'.` |
| `input: { document: 'file' }, output: { document: 'file' }, human: { sign: 'notary', in: 'document' }, price: 49` | `Type '"document"' is not assignable to type '"✗ add a jurisdiction input to route a signer"'.` |

## In the example brands

The lines that use it in the example brands, as their files write them, and what `check` read aloud for each file.

```ts title="legal · services/contract-review.ts · 16 lines"
  input: { contract: 'file', client: 'party', client_region: 'jurisdiction: such as US-CA', goals: 'text?' },
  output: { flags: 'file', memo: 'file' },
```

```txt title="npx services.dev check · captured/legal-walk.txt"
services/contract-review.ts · 16 lines · $99 per job, within 48 hours, charged on acceptance.
  steps   consent · client · consent → flag · ai → attack · ai · adversarial → advise · attorney · client · stamped · 2-item checklist → send · ai
```

[The legal example](https://services.dev/docs/examples/legal.md) runs every one of its files, captured.

```ts title="tax · services/amended-return.ts · 22 lines"
  input: {
  output: { return: 'file: the return packet, every jurisdiction', returns: 'file[]', workpapers: 'file', statements: 'file[]?: each owner\'s adjusted statement', tax: 'money{}', balance_due: 'money{}', carryforwards: carryforwardList, receipts: 'text[]' },
```

```txt title="npx services.dev check · captured/tax-check.txt"
services/amended-return.ts · 22 lines · $900 per job, within 30 days, charged when file or aar is accepted.
  steps   compute · code · cites depreciation and carryforward schedules → draft · ai · cites the workpapers and the records the organizer took → check · ai · adversarial · 2 lenses → prepare · preparer · * · 1-item checklist → sign · signer · * · stamped in the paid-preparer block → authorize · owner · sign → file · IRS and states, unless a partnership → aar · IRS · Form 8082, for a partnership · emits k1.adjusted
```

[The tax example](https://services.dev/docs/examples/tax.md) runs every one of its files, captured.

---

- Up: [Service()](https://services.dev/docs/service.md)
- Previous: [Service()](https://services.dev/docs/service.md)
- Next: [deliver](https://services.dev/docs/service/deliver.md)