mail-address-semantics/mas-v0.2-spec/SPECIFICATION.md

# Mail Address Semantics (MAS) v0.2 (draft)

## 1. Status and normative language

This document is a **draft** of MAS v0.2. It includes v0.1.1 and adds
statute-enabled stand-ins for `=` and `!`, destination transforms for
generators, and a statute-declared resource-identifier case rule (see
`CHANGELOG.md`). The canonical grammar is unchanged from v0.1.1.

A statute opts into v0.2 features by declaring `"mas_version": "0.2"`. A
v0.1 statute stays valid and is interpreted under v0.1.1 rules.

The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, **SHOULD NOT**,
**RECOMMENDED**, **MAY**, and **OPTIONAL** are to be interpreted as described
in BCP 14 when, and only when, they appear in uppercase.

MAS is an overlay on ordinary email addressing. It does not replace SMTP,
establish identity, grant authority, define delivery topology, or create
contractual commitments.

## 2. Scope

MAS v0.1 standardizes:

1. non-structural naming hints for people, actors, and functions;
2. structured resource targets using `=`;
3. facets using `+`;
4. an optional interaction profile using `!`;
5. exact-host statute discovery;
6. conservative equivalence behavior;
7. parser and generator conformance.

`$` and `^` are reserved. They have no MAS v0.1 meaning.

## 3. Profiles

### 3.1 Profile P1 — Naming + Resource

P1 is the base v0.1 profile.

- `.` MAY be used as a person-style naming separator.
- `-` MAY be used as an actor-style naming separator.
- `_` MAY be used as a function-style naming separator.
- `=` structurally binds a resource type to a resource identifier.
- `+` structurally adds one facet.

`.`, `-`, and `_` never classify an address by themselves.

### 3.2 Profile P2 — Interaction

P2 extends P1 with `!`.

`TARGET!MODE` requests that the addressed endpoint continue the interaction
using `MODE` as the preferred interaction mode.

The address does not state which party initiates a non-email leg and does not
constitute acceptance. Acceptance is external to the address.

### 3.3 Profile P3 — Economic

P3 is not defined in v0.1.

`$` and `^` are reserved so that later profiles may define consideration and
conditions without creating v0.1 parsing ambiguity.

## 4. Canonical ASCII local-part

The normative v0.1 machine grammar is the ABNF in
`grammar/mas-v0.2.abnf`.

Canonical MAS v0.1 local-parts are unquoted ASCII dot-atom-like strings.
Quoted local-parts and SMTPUTF8 local-parts are outside the canonical v0.1
machine grammar.

A MAS-aware implementation MAY transport such non-canonical email addresses
as ordinary email, but MUST NOT claim that they are canonical MAS v0.1
addresses.

A quoted local-part whose content, after removing the quotes and with no
quoted-pairs, is a valid canonical MAS local-part is equivalent to that
unquoted form (RFC 5321 treats unnecessary quoting as equivalent, and MTAs
remove such quotes in transit). Receivers MUST treat the two identically.
Generators MUST emit the unquoted form. Parsers that check canonical syntax
still reject the quoted form.

### 4.1 Target

A target is non-empty.

A target without `=` is opaque. Its semantic kind MUST NOT be inferred from
`.`, `-`, or `_`.

If a target contains `=`, the target is a resource target:

- text before the first `=` is `resource-type`;
- text after the first `=` is `resource-id`;
- neither may be empty;
- subsequent `=` characters are resource-id data.

Examples:

    ticket=PR42
    invoice=RE=2026-4711

The second example has resource type `invoice` and resource id
`RE=2026-4711`.

### 4.2 Facet

A facet is introduced by `+`.

`+` MAY occur at most once and its value MUST be non-empty.

    ticket=PR42+comments

The base target remains meaningful if a mail system strips the facet. MAS
therefore treats facet loss as graceful degradation:

    ticket=PR42+comments  ->  ticket=PR42

This is a semantic design property, not a preservation guarantee.

### 4.3 Interaction

An interaction preference is introduced by `!`.

`!` MAY occur at most once and its value MUST be non-empty.

P2 examples:

    ticket!callback
    ticket=PR42!web

Canonical operator order is:

    TARGET [+FACET] [!INTERACTION]

Non-canonical order is invalid MAS syntax. A conforming parser MUST reject it
and MUST NOT silently reorder it.

### 4.4 Composition rule

A parser implementing P2 MUST be able to parse the canonical combined form:

    TARGET+FACET!INTERACTION

A v0.1 generator MUST NOT emit both `+` and `!` in the same generated
local-part. Implementations requiring both semantics SHOULD move one of them
to external metadata.

This deliberately makes receivers slightly more tolerant than generators
while retaining one canonical parse.

### 4.5 Reserved characters

Within canonical MAS v0.1 structured values:

    + ! $ ^

are reserved.

MAS v0.1 defines no escaping mechanism.

A percent-looking sequence such as `%2B` is ordinary data in v0.1 and MUST NOT
be percent-decoded by the MAS parser.

## 5. Naming semantics

The following are style conventions only:

    bernd.worsch@example.org       person-like
    research-companion@example.org actor-like
    invoice_ingest@example.org     function-like

They are not classifier rules.

Examples such as these remain opaque without statute metadata:

    anne-marie.schmidt@example.org
    support@example.org
    happy-helper.v2@example.org

A domain registry or statute metadata determines semantic kind.

## 6. Resource semantics

A resource address identifies a communication endpoint associated with a
resource.

    ticket=PR42@example.org

It does not grant access to, mutation of, or knowledge about the resource.

Resource addressability and resource mutability are independent.

A closed resource MAY remain addressable. A receiver MAY archive the mail,
reject mutation, return lifecycle information, or create a linked follow-up
resource.

### 6.1 Resource types

A resource type is lower-case: one or more words of `a-z` and `0-9`, joined
by single `-` or `_` characters (grammar rule `resource-type`). A
local-part whose part before the first `=` is not a valid resource type,
such as `Ticket=PR42`, is not a canonical MAS address.

Resource types are protocol tokens, not user data. Forwarders and list
servers commonly lower-case local-parts, so mixed-case types would not
survive transit.

A statute SHOULD enumerate resource types it recognizes.

Unknown resource types MUST NOT acquire application semantics solely because
they use `=` syntax.

### 6.2 Resource identifiers

Resource identifiers are correlation identifiers, not credentials.

Predictable identifiers are enumerable. Deployments SHOULD prefer
non-guessable external identifiers when addresses are widely forwarded or
exposed and enumeration is undesirable.

High entropy does not transform an identifier into an authorization token.

Forwarders, mailing lists and web forms commonly change the case of
local-parts. Generators SHOULD use resource identifiers whose meaning does
not depend on letter case, for example lower-case only or a
case-insensitive alphabet such as Crockford base32, and receivers SHOULD
then match them case-insensitively.

### 6.3 Stand-ins (v0.2)

Some endpoints, for example provider forwarding forms, refuse `=` or `!` in
an address. v0.2 defines two fixed **stand-ins** built from dashes only:

| Stand-in | Stands for | Statute switch |
|---|---|---|
| `--` | `=` (resource separator) | `alternate_syntax.resource: true` |
| `---` | `!` (interaction) | `alternate_syntax.interaction: true` |

The stand-ins are defined by this specification and are not configurable.
`+` has no stand-in; it is functional by default, and facet loss degrades
safely (§12).

A stand-in has meaning only in a namespace whose statute enables it.
Without the switch, `--` and `---` are ordinary characters (§6.1). A
stand-in form is not canonical: the parser treats it as an opaque target,
and only a statute-aware implementation interprets it.

**Matching order.** A statute-aware implementation interprets a local-part
in this order:

1. **Interaction.** If the interaction stand-in is enabled and the
   local-part ends in `---MODE`, where `MODE` is an interaction mode the
   statute enables, the suffix after the last such `---` is the
   interaction, equivalent to `!MODE`.
2. **Resource.** If the resource stand-in is enabled and the remaining
   target has the form `TYPE--ID`, where `TYPE` is a resource type the
   statute declares, it is equivalent to `TYPE=ID`. The split is at the
   first `--`.

| Received | Equivalent canonical form |
|---|---|
| `ticket---callback` | `ticket!callback` |
| `ticket--gs1---callback` | `ticket=gs1!callback` |
| `ticket--a---b` (`b` not an enabled mode) | `ticket=a---b` |
| `ticket--gs1+comments` | `ticket=gs1+comments` |

**Constraints.**

- Resource-type names never contain `--` (grammar, §6.1).
- Interaction mode names MUST NOT start with `-`.
- A namespace that enables the interaction stand-in MUST NOT issue resource
  identifiers containing `---`.
- A namespace with existing opaque names matching a stand-in pattern MUST
  NOT enable that stand-in.

Receivers MUST store, correlate and reply using the canonical form. The
equivalence key (§8) is always computed from the canonical form.

## 7. Interaction semantics

The recommended P2 initiation pattern is:

    ticket!callback@great-service.example

followed by creation or disclosure of a resource:

    ticket=GS-41872@great-service.example

The first address expresses interaction intent. The second names the resource
created or selected by the service.

`!callback` is a preference/request, not a command, guarantee, SLA, or proof
of acceptance.

The bare target in `ticket!callback` is an opaque target. It has no link
to the resource type `ticket` merely because the names are equal. A
statute declares the link on the address registry entry:

    "addresses": { "ticket": { "kind": "function", "intake_for": "ticket" } }

An address whose base target is registered with `intake_for: T` is the
*intake* for resource type `T`: mail to it requests creation or selection
of a resource of type `T`. The entry MUST have `kind` `function`, and `T`
MUST be a resource type the statute declares or inherits. Without such a
registration a target has no intake semantics, even if it equals a declared
resource type.

## 8. Address equivalence

MAS does not impose case folding, dot folding, alias folding, or Unicode
normalization in the absence of a successfully discovered statute.

If no statute is available, comparison is exact over the presented canonical
ASCII local-part.

A statute MAY declare:

- `exact` local-part comparison;
- `ascii-insensitive` local-part comparison;
- dot folding for explicitly named address kinds or registry entries.

Dot folding MUST NOT be assumed by default.

A v0.2 statute MAY declare `equivalence.resource_id_case`:

- `exact` (default): resource identifiers compare exactly, subject to
  `local_part_case`;
- `insensitive`: resource identifiers compare ASCII case-insensitively,
  even when `local_part_case` is `exact`. Nothing else is folded.

Generators for such a namespace SHOULD emit identifiers in lower case
(§6.2).

A-label/U-label domain processing follows the underlying IDNA-aware HTTPS and
DNS stack; MAS does not invent a second IDN mapping algorithm.

## 9. Unicode

SMTPUTF8 allows non-ASCII local-parts, but MAS v0.1 does not define a
canonical Unicode local-part grammar.

A statute may declare `unicode_local_part: true` for experimental/private
extensions. Such addresses MUST NOT be advertised as canonical MAS v0.1
machine syntax.

A future MAS version may define NFC normalization and Unicode comparison
rules. v0.1 deliberately avoids doing so.

## 10. Statute discovery

The intended discovery URI is:

    https://HOST/.well-known/mas

where `HOST` is the exact domain appearing after `@`.

For:

    anna.mueller@acme.coulomb.social

the lookup host is:

    acme.coulomb.social

A client MUST NOT walk to parent domains implicitly.

### 10.1 Registration caveat

RFC 8615 requires applications minting a new well-known URI suffix to
register it for general Internet use.

Therefore `/.well-known/mas` is a candidate MAS discovery location in this
draft. General public deployment SHOULD wait for the required registration.
Controlled deployments MAY use it by agreement.

### 10.2 Retrieval

A statute-aware client:

1. constructs the HTTPS URI for the exact host;
2. performs an HTTPS GET;
3. requires a successful 2xx response;
4. requires a document conforming to the v0.1 statute schema;
5. verifies that `namespace` equals the queried host after normal domain-name
   canonicalization;
6. otherwise treats discovery as failed.

Discovery failure does not make the email address invalid. It means MAS
semantics are unconfirmed.

### 10.3 Redirects

Clients SHOULD NOT follow cross-origin redirects for statute discovery.

Same-origin redirects MAY be followed.

A cross-origin policy transfer requires an explicit future delegation
mechanism and is not defined in v0.1.

### 10.4 Inheritance

No parent-domain inheritance is implicit.

A child statute MAY contain an `inherits` URI. v0.1 inheritance is
**defaults-only**:

- the parent document is fetched and validated independently;
- the child remains authoritative for its exact namespace;
- child values override inherited defaults;
- address registry entries are never inherited;
- resource types and interaction modes MAY be inherited;
- an inheritance cycle is invalid.

Implementations MAY choose not to implement inheritance. If they do not,
they MUST ignore `inherits` rather than walking DNS parents.

## 11. Statute document

The normative schema is:

    schema/mas-statute-v0.2.schema.json

The document describes:

- namespace and version;
- enabled profiles;
- accepted resource types;
- accepted interaction modes;
- equivalence policy;
- optional explicit address classification;
- optional inheritance;
- optional stand-in switches (`alternate_syntax`, v0.2);
- optional resource-identifier case rule (`equivalence.resource_id_case`, v0.2).

The statute is metadata, not an authorization database.

## 12. Deliverability and rewriting

RFC-validity is weaker than ecosystem compatibility.

Mailing lists, SRS, VERP, gateways, web forms, validators, and security
products may reject or rewrite otherwise legal local-parts.

Deployments MUST NOT assume preservation of MAS syntax through arbitrary
rewriting.

`+` is intentionally degradation-friendly: loss of a facet leaves the base
target.

`!` is intended primarily for cooperating environments where all relevant
systems are known to preserve it. Where an endpoint refuses it, a namespace
can enable the `---` stand-in (§6.3).

### 12.1 Destination transforms (v0.2)

A generator produces an address for a *destination*: a mail header, a
forwarding form, a list membership, a printed page. A **destination
transform** changes an address so that it fits a destination's constraints.
The set is closed:

| Transform | Effect | Allowed only if |
|---|---|---|
| `resource-alternate` | `TYPE=ID` → `TYPE--ID` | the statute enables `alternate_syntax.resource` |
| `interaction-alternate` | `!MODE` → `---MODE` | the statute enables `alternate_syntax.interaction` and `MODE` |
| `lowercase` | fold the local-part to lower case | the statute declares `resource_id_case: insensitive` |
| `drop-facet` | remove `+FACET` | always; only on explicit request |
| `drop-interaction` | remove `!MODE` | always; only on explicit request, with a warning |

A generator:

- MUST emit the canonical form when the destination allows it;
- MAY apply the transforms a destination needs, and only those the
  namespace's statute permits;
- MUST refuse, rather than emit a form the receiver would misread, when the
  destination needs a transform the statute does not permit;
- MUST check the length limit (§13) after all transforms and refuse rather
  than truncate.

Outbound service mail (From, Reply-To) stays canonical unless a destination
transform is known to be needed.

### 12.2 Integrating with constrained endpoints (informative)

To integrate with an endpoint that rejects or rewrites MAS syntax:

1. Observe what the endpoint refuses or rewrites.
2. Enable the matching acceptance in the statute (stand-ins, identifier
   case).
3. Describe the endpoint as a **destination profile** in the generator's
   configuration: the list of transforms it needs.

Concrete profiles are implementation configuration, not part of this
specification.

*Example.* An IONOS mail-forward form (observed 2026-10) refuses `=` and
forces lower case. With a statute that enables `alternate_syntax.resource`
and declares `resource_id_case: insensitive`, the profile
`resource-alternate` + `lowercase` turns `ticket=GS-85QJ8WC09P+comments`
into `ticket--gs-85qj8wc09p+comments`, which the receiving namespace
correlates to the original resource. Google Groups accepts `=` but stores
members in lower case, so it needs only `lowercase`.

## 13. Length

An SMTP local-part is limited to 64 octets.

Generators MUST enforce the underlying transport limit after encoding and
after destination transforms. `--` adds one octet and `---` adds two.

Because the budget is small, v0.1 permits at most one facet and one
interaction, and generators MUST NOT emit both simultaneously.

## 14. Security

1. MAS identifiers are not credentials.
2. Resource knowledge grants no authority.
3. Interaction selectors are not commands.
4. Dynamic addresses MUST define handling for bounces, unknown resources,
   expired resources, verification traffic, and abuse.
5. Receivers MUST avoid backscatter behavior.
6. Syntax-derived classifications MUST NOT substitute for statute metadata.
7. `$` and `^` MUST NOT be rendered as payment/contract semantics in v0.1.
8. Authentication remains external to MAS.
9. A statute endpoint is security-relevant configuration and SHOULD be
   protected with the same care as other origin-wide metadata.
10. A receiver that automatically replies to mail sent to an intake or
    interaction address turns any forged sender into outbound mail to a
    third party. Such a receiver SHOULD reply only when the sender is
    authenticated (for example DMARC alignment pass), MUST bound the volume
    of such replies (rate limits or caps), and MUST NOT reply to automated
    mail (`Auto-Submitted` other than `no`, or `Precedence` `bulk`, `list`
    or `junk`).

## 15. Conformance classes

### 15.1 P1 parser

A P1 parser:

- validates canonical ASCII syntax;
- parses resource binding and facet;
- rejects `!`, `$`, and `^` as MAS operators;
- does not classify opaque target kind by punctuation.

### 15.2 P2 parser

A P2 parser additionally parses `!`.

### 15.3 Generator

A generator:

- emits only canonical operator order;
- emits no empty component;
- emits no reserved operator within a value;
- emits at most one `+`;
- emits at most one `!`;
- MUST NOT emit both `+` and `!` in v0.1;
- enforces the SMTP local-part octet limit.

### 15.4 Statute-aware implementation

A statute-aware implementation additionally validates the discovery document
against the normative schema and applies only explicitly declared equivalence
and classification rules.

## 16. Reserved future work

Future specifications may define:

- Unicode canonical grammar;
- escaping;
- signed statutes and signed semantic assertions;
- interaction negotiation;
- service discovery;
- economic request/offer/acceptance/settlement;
- condition tokens;
- IANA registrations.

## 17. One-sentence definition

**Mail Address Semantics is a voluntary convention for naming people, actors
and functions, and for addressing resources, facets, and optional interaction
preferences through ordinary email addresses while keeping classification,
authority, authentication, equivalence, and delivery implementation explicit
and external to the address syntax.**