Linkumori CLN Format 1.0 (Final)

Status and scope

This document is CLN Format 1.0 in its final form. It supersedes the 1.0 text announced on 2 October 2026, and there is no compatibility mode for that earlier text.

It is written against the 1.0 announcement.

What it keeps. Every key, array and pattern of the earlier 1.0 text stays valid. A file written for that text loads without edits, so no converter is needed.

What it changes. Run order, duplicate handling, toggle ids, filter escaping, and the safety of redirects and remote rule files. There are ten changes in all.

No backward compatibility. Every rule in this document applies to every rule file. A file that relied on the earlier behavior runs differently; Changes for existing rule files lists the cases.

Summary of changes

1.0 final differs from the earlier 1.0 text in ten places, and all ten apply to every rule file.

The earlier text is silent on rows 8 and 9, so 1.0 final writes them down.

File structure

A rule file gains one optional top-level key, cln, which names the format version. Its only valid value is "1.0".

{
  "cln": "1.0",
  "defaults": { "requestTypes": ["main_frame"] },
  "providers": {
    "shop": {
      "domainPatterns": ["||shop.example^"],
      "rules": ["utm_source"]
    }
  }
}

The top-level keys are now cln, providers, metadata and defaults. Only providers is required.

One 1.0. There is no separate value for the earlier 1.0 text. A file with no key and a file with "1.0" both get the rules in this document.

Why the key exists. It lets a later format version be told apart from 1.0 without guessing from the file's shape.

Why not version. The ClearURLs new rule format uses a top-level version, and Linkumori imports those files. A separate key keeps format detection unambiguous: version means ClearURLs, cln means CLN.

Rejection. A rejected remote file is not loaded and Remote Rules Health reports it as an error. A rejected built-in or custom file fails lint-rules.

Processing order

Raw rules always run before field rules, and order only sorts entries inside one stage. This settles the open question in the earlier 1.0 text: the raw to field boundary cannot be crossed.

The stage sequence for each matching provider is unchanged:

1. exceptions (skip the provider if one matches)
2. redirections
3. fieldRedirections
4. completeProvider
5. rawRules
6. rules and referralMarketing
7. $removeparam filters

Stages 5 and 6 are sorted by one key, which gains a leading stage part:

(stage, orderGroup, order, rank, arrayIndex)

Read the key left to right; the first part that differs decides.

• Stage decides first. No order value moves a field rule ahead of a raw rule.
• Inside a stage, ordered entries run before unordered ones, lowest order first.
• At equal order, or with none, entries run by rank, then by arrayIndex.
• The key is total. Every provider has exactly one sequence.

A cleanup that must happen before a raw rule is written as a raw rule. A raw rule is a regex against the whole URL, so it can express any parameter removal.

Three things carry over from the earlier 1.0 text. Entries that are off are left out. $removeparam filters run after stage 6. Neither they nor @@ entries may carry an order.

Worked example

{
  "cln": "1.0",
  "providers": {
    "shop": {
      "domainPatterns": ["||shop.example^"],
      "rawRules": [
        "\\/ref=[^/?]*",
        { "id": "strip-jsessionid", "matchPattern": ";jsessionid=[^/?#]*", "order": 20 }
      ],
      "rules": [
        "utm_source",
        { "id": "token-rewrite", "matchPattern": "token", "replacePattern": "clean-§1§", "order": 5 },
        "fbclid",
        { "id": "aff-id", "matchPattern": "aff_id", "referralMarketing": true },
        { "id": "sid", "matchPattern": "sid", "order": 20 },
        "$removeparam=/^pk_/"
      ],
      "referralMarketing": ["tag"]
    }
  }
}

With "allow referral marketing" off, the provider runs in this sequence. The last column shows where the earlier 1.0 text put the same entry.

The $removeparam=/^pk_/ filter runs after row 8. In the earlier 1.0 text, token-rewrite read the URL before either raw rule had cleaned it. Here both raw rules finish first.

Run-order calculator

Paste a CLN rule file and pick a provider to see the sequence its rawRules, rules and referralMarketing entries run in under this document's sort key. It applies the rules above and in Same text twice; it runs in your browser and sends nothing anywhere. The sample is the worked example.

Whole-number matchPattern entries

An entry written like "3" or "20" now runs at its array position, the same as any other entry.

In the earlier 1.0 text these entries jumped ahead of their group, smallest number first. The cause is recorded in the 1.0 docs update: the engine keys these lists by text, and JavaScript lists number-like keys first. 1.0 final removes the two whole-number rows from the rank table and makes arrayIndex the array position in every case.

Engine requirement. An engine that keys rule lists by text must use a structure that keeps insertion order for every key, such as a Map. A plain JavaScript object does not qualify.

Lint. The warning for a whole-number entry without an order is withdrawn.

Worked example

{
  "cln": "1.0",
  "providers": {
    "numbers": {
      "domainPatterns": ["||numbers.example^"],
      "rawRules": ["r", "3"],
      "rules": ["a", "20", { "matchPattern": "9", "referralMarketing": true }, "b"],
      "referralMarketing": ["rm", "5"]
    }
  }
}

With "allow referral marketing" off:

Every entry runs where the file lists it. Rows 6 to 8 follow the unmarked rules entries because of rank, not because of their text.

Same text twice

A definition that replaces an earlier one now keeps the earlier one's position, order included, unless it sets its own.

The groups are unchanged: raw (rawRules), field (rules entries without the referral mark), and referral (marked rules objects, then referralMarketing). Two entries with the same matchPattern text in one group are still one entry. The last definition that isn't off still wins whole: its id, its replacePattern and every other key.

Two things change.

Position. A winning definition without its own order takes two things from the earlier definitions that aren't off. Its arrayIndex comes from the first one. Its order comes from the nearest earlier one that has an order key. Under the earlier 1.0 text it took the arrayIndex and lost the order.

Ids. The id and aliases of every replaced definition resolve to the winner. Under the earlier 1.0 text, toggling them switched nothing. See Rule ids and toggles.

"order": null is new. It means "no order, and do not inherit one". It is the explicit way to drop an order set by an earlier definition.

Across field and referral. Unchanged in substance. While referral-marketing rules run, a referral entry with the same text as a field entry replaces it. Without its own order it takes the field entry's place, now including that entry's order.

Raw and field. Entries with the same text in the raw and field groups still do not collide; both run.

Within one file. Two different entries with the same text in one array remain a lint-rules error. Inheritance exists for merges across files, not as an authoring feature.

Overload mode

A remote copy of a built-in rule no longer drops the built-in order by accident, and a replaced rule is reported as a notice, not an error.

Four parts of overload mode are unchanged from the earlier 1.0 text:

• Load order. Remote files merge with each other in listed order, then with the built-in rules: built-in first, remote after.
• Which providers merge. Only those with the same domainPatterns or urlPattern, and the same methods, resourceTypes, completeProvider and forceRedirection.
• Joining. rules, rawRules and referralMarketing are each joined in load order.
• Exact copies. Only entries that are exactly alike count once while joining.

Two parts change.

Position inheritance. The rule in Same text twice applies to the merged provider. A remote copy without an order keeps the order of the copy it replaces. To drop it, the remote copy sets "order": null.

Remote Rules Health levels. A rule replaced by a merge is a notice that names the replacing file. An error is reserved for a file or entry that did not load.

Rule ids and toggles

A toggle is now keyed by provider and rule together, as providerKey::id, so two providers can use the same rule id without sharing a switch.

The earlier 1.0 text keys the toggle off the rule id alone and does not describe namespacing. 1.0 final specifies it.

• Toggle key. providerKey::id, where providerKey is the provider's key under providers. Example: shop::token-rewrite. An id cannot contain a colon, so the key splits at its last ::.
• Unique in a provider. Within one provider of one file, every id and every alias is distinct. A repeat is a lint-rules error. Generated ids count.
• Replaced definitions. When one definition replaces another, the id and aliases of each replaced definition resolve to the winner. Toggling any of them switches the one rule that runs.
• Saved toggles. A toggle saved under a bare id switches nothing. Toggles keyed providerKey::id or by match pattern keep working. A person switches a rule off again in the custom rules editor.
• Shared provider keys. Two providers that share a key but do not merge also share toggles for equal ids. Remote Rules Health warns about each such pair.
• Generated ids. Unchanged. An id is still generated from the list and the matchPattern text when left out, and still changes when that text is edited.

Worked example

The built-in rules define token with "id": "token-rewrite" in provider shop. A person switches shop::token-rewrite off. Later a remote file replaces that rule with a definition whose id is tok.

$removeparam and @@ exceptions

Any parameter name can now be targeted, and an @@ entry is matched against the URL the provider received.

Value escapes

A backslash in a $removeparam value makes the next character literal. In the earlier 1.0 text the first character after = picks the value form, so a parameter named ~foo, or one starting with |, could not be targeted.

• $removeparam=\~foo removes the parameter named ~foo.
• $removeparam=\|foo removes the parameter named |foo.
• $removeparam=\/foo/ removes the parameter named /foo/.
• $removeparam=a\,b removes the parameter named a,b. The comma does not start the modifier list.
• $removeparam=\\foo removes the parameter named \foo.

Three rules bound the feature:

• Only these five. \~, \|, \/, \, and \\ are the valid escapes in a name value. A backslash before any other character is a lint-rules error.
• Regex values. Inside a /regex/ value the backslash keeps its regex meaning. A comma after a backslash never starts the modifier list, in any value form.
• Everywhere a value is read. The escapes apply in rules, referralMarketing, fieldRedirections and @@ entries.

In a JSON rule file each backslash is written twice: "$removeparam=\\~foo".

Where @@ is matched

An @@ entry's pattern and modifiers are checked against the URL as the provider received it at the start of the current cycle. In the earlier 1.0 text they were checked after the provider's raw rules had run, so an exception scoped to a path that a raw rule deletes stopped matching.

{
  "cln": "1.0",
  "providers": {
    "shop": {
      "domainPatterns": ["||shop.example^"],
      "rawRules": ["\\/ref=[^/?]*"],
      "rules": [
        "$removeparam=tag",
        "@@||shop.example^/ref=$removeparam=tag"
      ]
    }
  }
}

For https://shop.example/ref=abc?tag=1:

Unchanged

• An @@ entry guards only against $removeparam filters. A plain rules entry still removes its parameter, and raw rules keep their own @@…$rawrule= entries.
• An @@ entry has no place in the run order and cannot carry an order.
• An @@ entry still reaches into other providers' filters on pages its own provider matches. A remote file that does this now shows the except capability; see the next section.

Redirect and block safety

A redirect may only go to an absolute http or https URL, processing always terminates, and a remote file cannot redirect or block until the person accepts that.

Redirect targets

A redirect target is valid when it parses as an absolute URL, its scheme is http or https, and it has a host.

The check covers all three sources of a target: the capture group of a redirections regex, the fixed target of a $redirect= entry, and the parameter value picked by fieldRedirections. It runs after the entry's preprocessors.

• Invalid target. No redirect happens. The entry is treated as not matching, and later stages run on the unchanged URL.
• Cross-origin raw rule. A raw rule whose result has a different scheme, host or port from its input is a redirect, whether it rewrites with a replacePattern or only deletes text. It needs a valid target and, in a remote file, the redirect capability. Without them the rule leaves the URL unchanged. Deleting text can change the host as surely as a rewrite can: secure- deleted from https://secure-bank.example/ gives https://bank.example/, another site.
• Lint. A $redirect= entry whose fixed target is not http or https is a lint-rules error.

Termination

Processing a request ends after a bounded number of cycles. The earlier 1.0 text says the cycle repeats on each new URL and states no bound. Read literally, a rewrite such as clean-§1§ would apply again on every cycle.

• Cycle cap. At most 10 cycles run per request. At the cap, processing stops and the URL is used as it stands.
• Unbounded mode. An engine may offer a setting, off by default, that removes the cycle cap. Rewrites still run once and no-op steps still do not count. Processing then ends when a cycle changes nothing, or when the browser stops a redirect loop.
• Rewrites run once. An entry with a replacePattern applies at most once per request.
• No-op steps. A step whose output equals its input is not a change and does not start a new cycle.

Remote file capabilities

A remote file's capabilities are derived from its content when it loads. A file does not declare them.

• Built-in and custom rules hold every capability.
• Acceptance is given per remote file and per capability. Until then, that file's redirect or block entries stay inactive and the rest of the file loads.
• Updates. When an update gives a file a capability it did not have, the new capability's entries stay inactive until accepted.
• Untraceable entries. When an engine cannot tell which remote file an entry came from, the entry gets only the capabilities that every configured remote file has accepted.
• Existing installs. No capability carries over. A remote file configured before this rule starts with only the capabilities active on load, and its redirect and block entries wait for acceptance like any other file's.
• Visibility. Remote Rules Health lists each remote file's capabilities.

Conformance

An engine conforms to CLN 1.0 when it reproduces every worked example and table in this document and the vectors below.

Lint checks

The warning for a whole-number matchPattern without an order is withdrawn. Position no longer depends on it.

Run-order vectors

The worked examples under Processing order and Whole-number matchPattern entries are normative. So are the result tables under Same text twice, Overload mode and Rule ids and toggles.

Redirect vectors

The provider matches site.example and has "fieldRedirections": ["redirect"].

In each "no redirect" row the provider's later stages still run on the request URL.

Termination vector

The token-rewrite rule from Processing order runs against https://shop.example/?token=abc123. The result is https://shop.example/?token=clean-abc123, and it does not change on any later cycle.

Changes for existing rule files

Every file written for the earlier 1.0 text is a valid 1.0 final file, so there is no converter and no compatibility mode. Five behaviors change, and a file that relied on one needs an edit.

Four engine rules also take effect for every file:

• A redirect to a relative target, or to a scheme other than http or https, no longer happens.
• A rewrite applies once per request, and processing stops after 10 cycles.
• A remote file's redirects and blocks wait for acceptance, including files installed before this change.
• A raw rule that deletes text no longer changes the scheme, host or port unless the result is a valid target and, in a remote file, redirect is accepted (Linkumori after v100.69.0).

A toggle saved under a bare id no longer applies. Toggles keyed providerKey::id or by match pattern keep working.

Deferred to 2.0

1.0 final leaves the file layout alone, so six known problems stay open for 2.0.

• One rules array. The single-array candidate from the 1.0 announcement is still the main design choice. The other candidate, an explicit stage key, has little left to add once order cannot cross stages.
• Two spellings for referral marketing. The referralMarketing array and the "referralMarketing": true flag both remain.
• String mini-languages. One entry string can still be a name, a name regex, a domain pattern or a filter.
• Steps outside the sort. Redirects keep their own arrays, and $removeparam filters still run last and cannot be ordered.
• No converter. The earlier 1.0 text maps concepts to the ClearURLs formats but defines no converter in either direction. 1.0 final does not add one.
• Generated ids. An id generated from matchPattern text still changes when that text is edited.

Sources

• Announcing Linkumori CLN Format 1.0, discussion #163, read in full on 2 October 2026. Every statement about the earlier 1.0 text comes from it, including the ClearURLs version key.
• Linkumori-Addon pull request #162: the cause of whole-number ordering.
• Linkumori-Addon pull request #149: Linkumori reads the ClearURLs formats.

Where the earlier 1.0 text is silent, this document says so and sets a rule.

Generated from docs/cln-format-1.0.md on the main branch. Found a problem? Open an issue.