Linkumori CLN Format 1.0

This page describes CLN Format 1.0 in its final form. The changes from the earlier 1.0 text, and why, are in CLN Format 1.0 (Final).

Linkumori CLN (Clean Link Notation) is the JSON rule format Linkumori uses to strip tracking parameters, rewrite URL text, and redirect around trackers. A rule file is one JSON object with a providers object (and, optionally, cln, metadata, defaults and, in a remote file, patches). Each key under providers is a name you choose; its value is a provider object.

The optional top-level cln key names the format version. Its only valid value is "1.0"; a file without it loads as 1.0 too, and a file with any other value is rejected (a remote file is not loaded and Remote Rules Health reports it; a built-in or custom file fails lint-rules). It is not called version because the ClearURLs new rule format already uses that key.

{
  "cln": "1.0",
  "providers": {
    "amazon": {
      "domainPatterns": ["||amazon.*^"],
      "rules": ["qid", "$removeparam=/^pd_rd_[a-z]*$/i"],
      "referralMarketing": ["tag"],
      "exceptions": ["||amazon.com^/gp/redirector.html"],
      "rawRules": ["\\/ref=[^/?]*"]
    }
  }
}

Provider fields

Patterns

Used in domainPatterns, and in front of exceptions, redirections, $removeparam, and raw rules.

^ means end-of-host or any separator (/ ? : or end of URL). * is a wildcard. A single \| needs a scheme after it (\|https://…) — for a domain you always want \|\|.

Worked example

||smile.amazon.*^

rules / referralMarketing

Each entry removes a parameter, from the query (?a=1) or fragment (#a=1):

To strip a parameter on only some of a provider's URLs, put a pattern in front of $removeparam:

"rules": ["qid", "||amazon.de^$removeparam=tag"]

referralMarketing uses the exact same syntax, but only runs while the person hasn't turned on "allow referral marketing."

$removeparam filters

Syntax

[@@][pattern]$removeparam[=value][,modifier,modifier,…]

Five pieces, four of them optional:

• @@ (optional) — turns this into an exception: it keeps a parameter instead of removing it, rather than matching anything itself. See "Exceptions" below.
• pattern (optional) — a domain pattern (§Patterns) narrowing the filter to only some of the provider's URLs, e.g. ||amazon.de^. Leave it out and the filter applies to every URL the provider already matches — it can only narrow, never widen, what the provider covers.
• $removeparam — the keyword itself; always required.
• =value (optional) — which parameter(s) to target. Leave it out entirely (just $removeparam) to remove every parameter.
• ,modifier,modifier,… (optional) — comma-separated conditions narrowing when the filter fires. Every modifier listed must hold; there's no "or" between them.

Value

The first character after = decides what's targeted:

A backslash makes the next character literal, so any parameter name can be targeted:

• Only these five. \~, \|, \/, \, and \\ are the escapes in a name value; a backslash before any other character is a lint-rules error.
• Regex values keep the backslash's regex meaning. A comma after a backslash never starts the modifier list, in any value form.
• Everywhere a value is read: rules, referralMarketing, fieldRedirections and @@ entries.
• In JSON each backslash is written twice: "$removeparam=\\~foo".

Modifiers

Everything after the first comma — one comma-separated condition per modifier. Every modifier listed must hold; there's no "or" between them. ~ in front of a domain, method, or request-type value excludes it instead of requiring it. The four *-party modifiers are mutually exclusive with each other (combining opposites is rejected).

Any request-type row above can be written with a leading ~ (e.g. ~xmlhttprequest) to exclude that type instead of requiring it.

Worked example

||example.com^$removeparam=sid,domain=~partner.com,method=get,third-party

All four conditions must hold at once for sid to be stripped.

Exceptions (@@)

A filter beginning with @@ keeps the parameter instead of removing it — the pattern and modifiers work exactly the same way, they just flip the outcome:

"rules": ["$removeparam=ref", "@@||github.com^$removeparam=ref"]

Here every provider-matched URL loses ref, except on github.com, where it's kept. An @@ entry also reaches into other providers' filters when the request comes from a page this provider matches — handy for carving out one site from a site-wide rule defined elsewhere.

An @@ entry isn't a step with a place in the run order — where you list it doesn't matter, and it can't carry an order. For each parameter, the provider checks its @@ entries first and its $removeparam filters second, and a matching @@ entry keeps the parameter. It only guards against $removeparam filters: a plain rules entry such as "ref" still removes ref (use a rule object's exceptions for that), and raw rules have their own @@…$rawrule= entries. Its pattern and modifiers are checked against the URL as the provider received it at the start of the current cycle — before the provider's raw rules run — so an @@ entry scoped to a path that a raw rule deletes still matches:

"rawRules": ["\\/ref=[^/?]*"],
"rules": ["$removeparam=tag", "@@||shop.example^/ref=$removeparam=tag"]

For https://shop.example/ref=abc?tag=1 the raw rule deletes /ref=abc, and tag is kept: the @@ pattern is checked against the URL that still has /ref=abc.

rawRules

Regexes run against the whole URL — every match gets deleted:

"rawRules": ["\\/ref=[^/?]*"]

They run before rules, so they can strip things that aren't name=value pairs — like Amazon's /ref=… path segment. A raw rule can also carry a pattern and $removeparam-style options, with rawrule= last: \|\|amazon.*^/dp/$rawrule=\\/ref=[^/?]*. An @@…$rawrule= entry stops raw rules from running instead of matching anything itself. With nothing after rawrule= it stops every raw rule of the provider where its pattern matches; with a regex it stops the raw rules with that regex; as a rule object with a targetId it stops only the raw rule with that id or alias.

Worked example

||amazon.*^/dp/$rawrule=\/ref=[^/?]*

exceptions

Each entry is a regex against the full URL, or a domain pattern starting with \|:

"exceptions": ["^https?:\\/\\/mail\\.google\\.com\\/mail\\/u\\/", "||accounts.google.com^"]

If the URL matches, none of the provider's rules run for that request.

Worked example

^https?:\/\/mail\.google\.com\/mail\/u\/

Any URL matching this stops the whole provider — Gmail keeps its tracking-looking parameters intact.

redirections

Either a regex with exactly one capture group — the request goes to whatever that group captures:

^https?:\/\/(?:[a-z0-9-]+\.)*?google(?:\.[a-z]{2,}){1,}\/url\?.*?(?:url|q)=(https?[^&]+)

Or a fixed domain redirect:

"||go.example.com^$redirect=https://example.com/"

Redirect targets

A redirect only happens to an absolute http or https URL with a host. This holds for all three kinds of target — the capture group (or replacePattern) of a redirections regex, the fixed target of a $redirect= entry, and the parameter value a fieldRedirections entry picks — and is checked after the entry's preprocessors (and after percent-decoding). An invalid target makes the entry count as not matching: no redirect happens, and the provider's later stages run on the unchanged URL. lint-rules rejects a $redirect= entry whose fixed target isn't http or https.

A raw rule whose result has a different scheme, host or port from its input is a redirect too, whether it rewrites with a replacePattern or only deletes text (secure- deleted from https://secure-bank.example/ lands on another site): it needs a valid target, and in a remote file the redirect capability (§Remote file capabilities). Otherwise the rule leaves the URL as it was.

Worked example

^https?:\/\/(?:[a-z0-9-]+\.)*?google(?:\.[a-z]{2,}){1,}\/url\?.*?(?:url|q)=(https?[^&]+)

fieldRedirections

Names a parameter directly — its own value becomes the new URL, no regex needed:

"fieldRedirections": ["redirect", "continue_url"]

Same entry types as rules (name, name regex, or $removeparam filter used just to pick the parameter). Whichever matching parameter comes first in the URL wins.

Worked example

Given https://site.example/away?redirect=https://real-destination.example/page:

Rule objects

Any entry, in any list above, can be an object instead of a string — for a stable id, a custom run order, or a rewrite instead of a delete:

{
  "id": "token-rewrite",
  "matchPattern": "token",
  "replacePattern": "clean-§1§",
  "requestTypes": ["main_frame"],
  "exceptions": ["^https:\\/\\/example\\.com\\/keep"],
  "order": 5,
  "active": true
}

Worked example

Using the token-rewrite object above, against a URL containing ?token=abc123:

Result: ?token=abc123 becomes ?token=clean-abc123.

defaults

A top-level defaults block gives every rule of the file values it doesn't set itself, like the ClearURLs new rule format's defaults:

{
  "defaults": { "requestTypes": ["main_frame"], "exceptions": ["^https:\\/\\/example\\.com\\/keep"] },
  "providers": { … }
}

• A rule's own value always wins, and a rule's exceptions replace the default list rather than adding to it. A provider's own historyBypassProtection beats the file default too.
• Which lists: rules, rawRules, referralMarketing, redirections and fieldRedirections. A provider's exceptions list is left alone, so a default can't switch every exception off. |-pattern entries ($redirect= redirects) only use active.
• Per file: defaults are written into the file's own rules when it loads. Built-in, each remote file, and custom rules keep their own defaults, including when overload mode merges built-in and remote rules. Custom rules' defaults are edited in the custom rules editor, which also shows the defaults each loaded source uses.
• Your own defaults: in the custom rules editor, "Manage rule defaults" opens a form where you can fill in one defaults block of your own (and the custom rules' own) and choose where yours replaces the files' own:
  • Each source's own (the default): every file uses its own defaults, as above.
  • Yours for built-in and remote rules: built-in and every remote file use yours, and ignore their own defaults. Custom rules keep their own.
  • Yours for all rules: every rule uses yours, and no file's own defaults is used.

  A rule's own value still wins, and provider exceptions are still left alone.

• Editing a file's own defaults: the same form can edit the built-in rules' defaults and each loaded remote file's. Your version is stored in the extension, not in the file, and replaces that file's whole defaults block wherever the file's own would be used. "Reset to the file's defaults" drops it. An edit for a remote file is kept while that file is not loaded.
• Merging defaults: "Merge from sources…" combines the defaults of any sources you tick (your own, built-in, each remote file, custom). The result appears as "Merged defaults" in the list of sets; copy it into one of them, then save. Keys the sources agree on are taken as they are, and exceptions are always added together: the exceptions of the set on screen first, then every other source's, without duplicates. For each other key they disagree on you pick one source's value or, for requestTypes and preprocessors, the combined list (a source that leaves requestTypes out keeps every type allowed). Nothing is stored until you save.
• Complete providers: a completeProvider blocks every request it matches before any rule is looked at, so requestTypes and exceptions from defaults also limit the block. requestTypes, together with its rules' own, become the provider's resourceTypes unless it sets some. exceptions are added to the provider's exceptions.
• Checked: unknown keys and wrong types are errors in lint-rules and the editor, and a remote file with an invalid defaults block is rejected.

Processing order

For each matching provider: exceptions (skip if matched) → redirections → fieldRedirections → completeProvider → rawRules → rules/referralMarketing → $removeparam filters. A rule's order can move it earlier or later within its own stage, never across stages. First provider to change, redirect, or block the URL wins, then the cycle repeats on the new URL (§Termination).

Run order

Stages 5 and 6 — every rawRules, rules and referralMarketing entry of the provider, bare strings and rule objects alike, except $removeparam filters and their @@ exceptions, which always run afterwards (§Exceptions) — run in ascending order of one sort key:

(stage, orderGroup, order, rank, arrayIndex)

Entries that are off ("active": false, toggled off, or referral-marketing entries while the person allows referral marketing) are left out, and entries with the same text count once (§Same text twice). 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. 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.
• Inside a stage, ordered entries run before unordered ones, lowest order first. order: 10 doesn't mean "tenth": it means "after the stage's other ordered entries with order below 10, and before all of its unordered entries".
• At equal order, or with none, entries run by rank, then by arrayIndex: rules, then rules objects marked "referralMarketing": true, then referralMarketing, each in array order. So "referralMarketing": true moves an unordered entry after the provider's unmarked rules entries.
• Every entry runs at its array position. An entry written like "3" or "20" is no exception: it keeps its place like any other entry. (Under the earlier 1.0 text these jumped ahead of their group, because the engine kept its rule lists in plain objects; it now keeps them in order-preserving maps.)
• The key is total. Every provider has exactly one sequence.

Same text twice

Two entries with the same matchPattern text in one group are one entry, and only one definition of it takes effect. The groups are:

• The last definition that isn't off wins, whole — its id, its replacePattern and every other key. A later definition that's off doesn't remove an earlier one.
• Its place. A winning definition with its own numeric order sorts by its own order, rank and arrayIndex. One without its own order takes its rank and arrayIndex from the first definition that isn't off, and its order from the nearest earlier definition that has an order key.
• "order": null means "no order, and do not inherit one". It is the explicit way to drop an order set by an earlier definition; the definition then takes the first definition's place.
• Ids. The id and aliases of every replaced definition switch the winner on and off too (§Rule ids and toggles).
• Across field and referral: 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, including that entry's order. While the person allows referral marketing, the field entry runs alone.
• Raw and field entries with the same text don't collide — both run.

Inheritance exists for merges across files, not as an authoring feature: lint-rules and the editor reject two different entries with the same text in one array, and warn about an exact copy. They also warn about the same text in rules and referralMarketing, and in rules with and without "referralMarketing": true. $removeparam filters don't count here — each one runs.

Overload mode

In Patch mode + merge and No patch mode + merge, built-in rules and remote rule files load together, and one site can have a provider in more than one of them. Provider merging in either mode follows these rules:

The overload settings offer three strategies: Patch mode only applies remote patches to the built-in rules and omits remote provider rules; Patch mode + merge merges built-in and remote providers, then applies patches; No patch mode + merge merges the providers and skips remote patches. The strategy is used only while overload mode is enabled. If built-in rules are disabled, patch-only mode has no built-in rules to patch.

1. Load order. Your remote files are merged with each other first, in the order you list them. The result is then merged with the built-in rules: built-in providers first, remote ones after.
2. Which providers merge. Only providers with the same domainPatterns (or the same urlPattern) and the same methods, resourceTypes, completeProvider and forceRedirection. Any other provider stays separate and keeps its own rules.
3. Joining the lists. Each of rules, rawRules and referralMarketing is joined in load order — built-in entries first, then each remote file's.
4. Exact copies. Only entries that are exactly alike count once while joining. order is part of what makes two entries alike, "order": null included.

The merged provider then runs like any other, so §Same text twice applies: after a merge the last definition is the remote one — with several remote files, the last-listed file's. 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 lists each rule a merge replaces as a notice naming the file whose definition won; an error is reserved for a file or entry that did not load. It also warns when a merge puts the same text in rules from one file and in referralMarketing (or a rules entry with "referralMarketing": true) from another.

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:

Then rules[5] "$removeparam=/^pk_/", with the provider's other $removeparam filters — it's outside the sort. With "allow referral marketing" on, 7 and 8 are left out and the rest keep their order. Both raw rules finish before token-rewrite reads the URL.

Worked example — whole numbers

{
  "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.

Rule ids and toggles

A rule's on/off toggle is keyed by provider and rule together, providerKey::id (for example shop::token-rewrite), so two providers can use the same rule id without sharing a switch. The custom rules editor may also save it under the provider's match pattern (domainPattern:||shop.example^::token-rewrite); both forms work. An id can't contain a colon, so a 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 (§Same text twice), the id and aliases of each replaced definition switch the winner. Toggling any of them switches the one rule that runs.
• No bare ids. A toggle saved under a bare id, without its provider, switches nothing; switch the rule off again in the custom rules editor.
• Shared 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 are unchanged: an id is generated from the list and the matchPattern text when left out, and changes when that text is edited.

The built-in rules define token with "id": "token-rewrite" in provider shop, and the person switches shop::token-rewrite off. A remote file then replaces that rule with a definition whose id is tok: the remote definition runs, the saved toggle keeps it off, and both shop::tok and shop::token-rewrite switch it.

Termination

Processing a request always ends:

• Cycle cap. At most 10 cycles run per request — a cycle being one pass of the providers over the URL, repeated after each change or redirect. At the cap, processing stops and the URL is used as it stands.
• Unbounded mode. Settings → Unbounded cleaning cycles (off by default) removes the cycle cap, for rule chains that need more than 10 cycles. Rewrites still run once and no-op steps still don't count, so processing ends when a cycle changes nothing. But two rules that redirect to each other then loop until the browser gives up on the redirect chain, and the page doesn't load. Cleaning a copied link, the context menu and the rule tester have no browser redirect limit, so there cleaning also stops when the URL comes back to one it already produced. Turn it on only for rules you trust.
• Rewrites run once. An entry with a replacePattern applies at most once per request. token-rewrite above turns https://shop.example/?token=abc123 into https://shop.example/?token=clean-abc123, and that does not change on any later cycle.
• 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, in Remote Rules Health. Until then that file's redirect or block entries stay inactive — and its raw rules can't take a URL to another origin, by a rewrite or a deletion — while 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.
• Old merged cache. A cached copy of the remote rules saved before files were cached one by one can't be traced to its files. Until the next refresh, its redirect and block entries stay inactive unless every configured remote file has accepted that capability.
• No carry-over. Every remote file starts with only strip, rewrite and except, including files configured before capabilities existed; accept redirect and block in Remote Rules Health.
• Visibility. Remote Rules Health lists each remote file's capabilities.

Rule patches

A remote rule file can replace rules that are already loaded, from the built-in rules or from another remote file, without publishing a whole copy of them. It lists the replacements in a top-level patches array:

{
  "cln": "1.0",
  "patches": [
    {
      "target": "amazon::field-qid",
      "section": "rules",
      "replace": { "matchPattern": "qid", "requestTypes": ["main_frame"] },
      "description": "Only strip qid on page loads"
    },
    {
      "target": "domainPattern:||amazon.*^::strip-ref",
      "section": "rawRules",
      "replace": "\\/ref=[^/?#]*"
    }
  ]
}

• What it patches. Patches run after the remote files are merged (and, in overload mode, merged with the built-in rules), and before custom rules, so a custom provider still overrides a patched one. A file of only patches needs no providers; when every loaded remote file is such a file, the patches apply to the built-in rules. Without overload mode the built-in rules are not loaded next to remote files that have providers, so patches then only reach those remote files' rules. In overload No patch mode + merge, patch files are validated and loaded but their patches are not applied; in Patch mode only, remote provider rules are omitted and patches target the built-in rules.
• Matching. A patch replaces the rule in every loaded provider whose key or match pattern equals the target's provider part. Merging can rename providers (in overload mode, or when two files have the same pattern), so the domainPattern: / urlPattern: form is the one that always finds them.
• Ids and toggles. The replacement keeps the replaced rule's id unless it sets its own id; then the old id becomes one of its aliases. Either way, an on/off setting saved for the old rule keeps applying.
• Defaults. The patch file's defaults (or the defaults it gets, §defaults) apply to its replacements as they would to its own rules.
• Capabilities. A file's patches count toward its capabilities (§Remote file capabilities). A patch for a redirections or fieldRedirections rule is skipped until the file's redirect capability is accepted, and a patched raw rule can't take a URL to another origin until then.
• Order. Patches run in the order of the configured remote files, then in array order, so a later patch can replace an earlier patch's replacement (it kept the id).
• Checked. An invalid patches array (unknown keys, a malformed target, a missing section or replace) rejects the whole file, like an invalid defaults block; lint-rules reports the same problems. A patch whose target matches no loaded rule changes nothing.
• Visibility. Remote Rules Health lists each patch as applied, unmatched or skipped.

Possible 2.0 direction

Left for 2.0 (see CLN Format 1.0 (Final)):

• One rules array. All three kinds in a single rules array whose array order is the run order. An explicit stage key has little left to add now that order cannot cross stages.
• Two spellings for referral marketing, the referralMarketing array and the "referralMarketing": true flag.
• String mini-languages, redirects and $removeparam filters outside the sort, a converter to and from the ClearURLs formats, and generated ids that change with their text.

User whitelist

Separate from a provider's exceptions — this is a site the person has told the extension to leave alone entirely, no rule file involved. Entries look like example.com, *.example.com (root + subdomains), or example.* (any suffix). Whitelisting a page also covers everything it loads.

Generated from docs/filter-syntax.md on the main branch. Found a problem? Open an issue.