> ## Documentation Index
> Fetch the complete documentation index at: https://docs.utmkit.co/llms.txt
> Use this file to discover all available pages before exploring further.

# The convention

> The shape every UTM value in the workspace must have, and whether a link that breaks it is refused or only flagged.

The convention is the workspace's answer to "what does a well-formed UTM value look like". It has
four settings, it applies to every link created in the workspace — from the console, the
assistant, the API or the MCP — and it sits at the top of the Rules page,
[https://app.utmkit.co/rules](https://app.utmkit.co/rules).

## The four settings

* **Casing**: `lower`, `upper` or `any`.
* **Separator**: the character between words, `hyphen`, `underscore` or `any`.
* **Required parameters**: any of `utm_source`, `utm_medium`, `utm_campaign`, `utm_term` and
  `utm_content` that a link may not leave out.
* **A violation**: the mode. `block` refuses the link; `warn` creates it and reports the problem.

A value passes the format when it is words of letters a–z and digits joined by the separator, with
nothing before, after or doubled. `spring-launch` passes the defaults; `Spring Launch` and
`spring--launch` do not.

A workspace that has never touched the page runs on the defaults: lowercase, hyphen, nothing
required, block. The page says so plainly: they are defaults, and they are in force.

## Changing it

Owners and admins see **Edit the convention**; everyone else sees the rules and can change none.
The editor changes what the *next* link has to look like. Links already created keep the values
baked into them; the [audit](/en/rules/audit-existing-urls) is what finds the ones that no longer
comply.

If a colleague saves the convention while you have the editor open, your save is refused and you
are asked to reload and apply your change again, rather than silently overwriting theirs.

<Tip>
  The convention also shapes derived values. A campaign called "Spring Launch" contributes
  `utm_campaign=spring-launch` under the defaults and `SPRING_LAUNCH` under uppercase with
  underscores. See [Campaigns](/en/campaigns).
</Tip>

## What happens to a link that breaks it

In **block** mode the link is not created. The refusal names the parameter, the value and the
rule it broke, in one sentence you can act on:

* A value in the wrong shape: *utm\_source 'Newsletter' does not match this workspace's UTM
  convention (lowercase, letters and digits joined by '-').*
* A required parameter left out: *utm\_medium is required by this workspace's UTM convention and
  was not provided.*
* A value outside the approved list, or one a dependency rule forbids: the sentence lists what is
  allowed instead. See [Approved values](/en/rules/approved-values) and
  [Dependency rules](/en/rules/dependency-rules).

In **warn** mode the link is created and the same sentence travels with it: the assistant relays
it in the conversation, and the API returns it beside the link. Warn is not off; it is the mode
for a workspace adopting rules over links it already has.

One check runs on top of your own rules. A value that follows the convention but that Google
Analytics would file under the wrong channel — `utm_medium=newsletter`, which lands in
*Unassigned* instead of *Email* — is reported with that consequence and the spellings that work,
and is refused in block mode like any other violation.

<Note>
  Approving a value or recording a dependency rule must itself respect the format: `Facebook`
  cannot be approved under a lowercase convention.
</Note>

## From the API and the MCP

`GET /api/v1/rules/convention` reads the four settings and `PUT /api/v1/rules/convention` changes
them; the body is partial by design, so a rule you do not name is left alone. Reads need
`rules:read`, writes `rules:write`. The MCP tools are `get_convention` and `set_convention`;
`set_convention`, like every rules write, also requires the token holder to be an owner or admin,
so a member's token is refused for its role even when it carries the permission.