# Naming

Every name has one spelling, decided by what kind of thing it names.

| Kind of name | Form | Examples |
|---|---|---|
| Types and declared contracts (entities, failures, services, config, events) | `UpperCamelCase` | `Todo`, `TodoNotFound`, `ReminderMail` |
| Values, fields, parameters, constants, functions, actions, queries, jobs, variants | `lower_snake_case` | `due_at`, `order_total`, `overdue_reminders` |
| Standard library | lowercase namespace, always qualified | `temporal.in_zone(...)` |
| Keywords | lowercase | `function`, `return`, `match` |

Identifiers are ASCII letters, digits and underscores, and can't start with
a digit. The compiler checks the case and suggests the right spelling.

A name must convert to its file name and back unchanged, so a name can't
have two capitals in a row: write `VatRate`, not `VATRate`.

## Reserved words

The words that control flow or open a declaration are reserved. None of
them can name a declaration, parameter or variable, and using one as a name
is `syntax.expected_name`. They are `action`, `and`,
`assert`, `attempt`, `constant`, `decline`, `else`, `emit`, `entity`,
`fails`, `false`, `fixture`, `for`, `function`, `if`, `in`, `library`,
`match`, `mut`, `none`, `not`, `or`, `package`, `propagate`, `provide`,
`public`, `query`, `reject`, `resource`, `return`, `routes`, `schedule`,
`seed`, `subscriber`, `test`, `true`, `type`, `use` and `var`.

Inside a type's or entity's body one may name a field or an enum variant,
where `package: Text` and `Kind.library` can't be misread. Such a name is
always read through what holds it, `parcel.package`, and alone it is still
the word ([Names from reserved words](/docs/objects.md#names-from-reserved-words)).

A domain is named by its folder, so a folder named with a reserved word,
`domains/library/`, is `syntax.expected_name` once, at the folder. Where
the domain is used, `library.borrow(...)` or `library.borrow:` in root
`policy.jadpo`, the word is read as the domain's name and nothing more is
reported. A block whose names are wrong reports its first
`syntax.expected_name`: a later line in it is most often the same mistake,
reported once the first is fixed.

A setting the language defines may still use a reserved word as its key,
such as `package: Stripe.v2024_06_20` in a connection or `test:` in
configuration.

## Words that are names everywhere else

Some words mean something only where the language expects them, and can be
used as names anywhere else:

- `asc` and `desc`, a query's order;
- `end`, in templates;
- `matches`, the pattern operator;
- `input` and `value`;
- the words that open a declaration with no name: `acceptance`,
  `application`, `authentication`, `config`, `flags`, `locales`,
  `migration`, `policy`, `principal` and `suggestions`
  ([Suggestions](/docs/suggestions.md)).

`include`, `pick`, `omit` and `optional` build a type's fields
([Values and types](/docs/values-and-types.md)), so they can name anything but
a field. The standard-library and generated namespaces (`list`, `clock`,
`config` and the rest) can't name a domain or a library.