# PIP-0017 · Aliases

A readable name a subject chooses, issued within one network, resolved through FINDER like any other identifier. The address stays opaque.

## Why

A PATH address is opaque by design: `path:4a91c2f7e8d3` names no member, network or country, and follows the subject across providers ([PATH ADDRESS](/docs/address)). Nobody reads it out over the phone.

People already pay each other by readable names: PayID, PayNow, PromptPay, the PI-SPI alias directory, a username on a payment page. PATH places such names among the identifiers of [PATH ID](/docs/id) ([PIP-0007](/pips/0007)). This PIP defines one: the **alias**, a name a subject chooses and a network issues.

An alias does not replace the address. It is a key that FINDER resolves to the address, as a phone number is.

## The identifier

A new identifier type, `alias`.

| Field | Rule |
|---|---|
| Form | `alias:<network>:<name>` — `alias:openconnect:awa.diop` |
| `<network>` | The slug of the issuing network, as in its discovery document |
| `<name>` | `^[a-z0-9][a-z0-9._]{1,30}[a-z0-9]$`. Lower case. No two consecutive separators |
| Display | `@awa.diop`, with the network shown wherever more than one network is in reach |

The network is part of the identifier. The same `<name>` in two networks names two identifiers, which may belong to two subjects.

### Normalisation

Lower-cased and trimmed. Characters outside the form are refused, not mapped. Confusable characters are outside the form.

The separators `.` and `_` are removed before hashing. Names that differ only by separators are one alias: `awa.diop`, `awa_diop` and `awadiop` are issued at most once in a network, and each spelling resolves to it. The subject's chosen spelling is the one shown.

## Entering an alias

A payer enters `alias:<network>:<name>`, or a bare `@name`.

- `alias:<network>:<name>` designates one alias.
- A bare `@name` resolves in the network of the payer's member.
- A member in several networks shows the payer one match per network, each with its network, and lets the payer choose. It never picks one silently.

## Issuance

- An alias is issued by the network named in it, to one subject, at the request of that subject through a member.
- One active alias per subject per network.
- Verification is the claim itself: `verification_method` is `alias_claim`, and `verified_at` is the time of issue.
- An alias that is held, reserved or in quarantine is not available, and the answer does not say which.
- A network publishes its reserved names in its rulebook.
- A network may mark the alias of a `legal_entity` subject as verified. The marker rests on a [PATH ID attestation](/docs/id#attestations) of the entity's `lei` or `reg` identifier, and the rulebook states the rule.

## Discoverability

| Type | Default |
|---|---|
| `alias` | `network` |

The rules of [PATH ID](/docs/id) apply unchanged: per-identifier discoverability, subject-level withdrawal, indistinguishable negatives, and the budgets of the network.

## Resolution

An alias is resolved like any other key ([PATH FINDER](/docs/finder)):

1. **SONAR** — which member holds this alias. Answered by the issuing network.
2. **RESOLVER** — what the destination accepts. Answered by the holding member, with `standing`.
3. **Payee check** — verify or display the name before sending ([PIP-0013](/pips/0013)).

An alias never resolves to another identifier of the subject.

## Changes and release

- A subject may change its alias. The number of changes in twelve months is set by the network.
- A released alias leaves the directory at once, and is not issued again before a quarantine set by the network.
- A subject that moves to another member of the same network keeps its alias. The issuing network records the new holder, and the new member registers the alias for the subject. A transfer is not a change.

## Where the rules are published

The network sets the quarantine and the change limit in its rulebook. Every member's discovery document states them, with the values of its network:

```json
"finder": {
  "aliases": { "quarantine_days": 90, "changes_per_year": 2 }
}
```

A member whose network issues aliases lists `alias` under `capabilities.identifier_types`.

## Outside the protocol

How a member shows an alias on its own pages, for example a payment page at `<host>/<name>`, is a product choice. Such a page is not a PATH link: the content of a code remains `https://<host>/path/<ref>` ([PATH INTEROP](/docs/interop)).

## Interface

| Call | Effect |
|---|---|
| `POST /identifiers` with `identifier_type: "alias"` | Issues the alias to the subject. `verification_method` is set to `alias_claim` |
| `POST /identifiers/{id}/release` | Releases it. The answer states the quarantine in days |
| `POST /identifiers/{id}/transfer` | Moves it to another member of the network, named in `to_member` |

Errors: `path.id.alias_unavailable`, `path.id.alias_already_held`, `path.id.alias_change_limit` ([Errors](/docs/errors)).

The SDK parses an alias with `parseAlias`, lists what a payer's entry designates with `aliasCandidates`, and formats it with `displayAlias`.

## Compatibility

Additive. Implementations that do not know the type ignore it, as with any unknown identifier type.