Search Configuration Schema (Archived)

This document outlines the details of the schema and how the various sub-parts interact. For the full fields and descriptions, please see the schema itself.

Note

In the examples, only relevant properties are displayed.

Overview

The configuration is a JSON blob which is object with a data property which is an array of engines:

{
  data: [
    {
      // engine 1 details
    },
    {
      // engine 2 details
    }
  ]
}

Engine Objects

An engine’s details are located in the properties of the object associated with it. An engine that is deployed globally could be listed simply as:

{
  "default": "no",
  "telemetryId": "engine1-telem",
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
    }
  }]
}

The appliesTo section is an array of objects. At least one object is required to specify which regions/locales the engine is included within. If an appliesTo object lists additional attributes then these will override any attributes at the top-level.

For example, a more complex engine definition may be available only to users located specific regions or with certain locales. For example:

{
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [{
    "included": {
      "region": "us"
    },
    "webExtension": {
      "id": "web-us@ext"
    }
  }, {
    "included": {
      "region": "gb"
    },
    "webExtension": {
      "id": "web-gb@ext"
    }
  }]
}

In this case users identified as being in the US region would use the WebExtension with identifier web-us@ext. GB region users would get web-gb@ext, and all other users would get web@ext.

To direct search engines to pull _locale data from a specific locale directory, you can use webExtension.locales.

For example, in this code block:

{
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [
    {
      "included": {
        "locales": "en-US"
      },
      "webExtension": {
        "locales": [
          "us"
        ]
      }
    }, {
      "included": {
        "locales": "en-GB"
      },
      "webExtension": {
        "locales": [
          "uk"
        ]
      }
    }
  ]
}

There should exist a us and uk folder in the locales directory of the extension, web.

If a locale is not provided, webExtension.locales is set to SearchUtils.DEFAULT_TAG.

Search Extensions directory

Example of a locales directory

Special Attributes

$USER_LOCALE

If a webExtension.locales property contains an element with the value "$USER_LOCALE" then the special value will be replaced in the configuration object with the users locale. For example:

{
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [{
    "included": {
      "locales": {
        "matches": [
          "en-US",
          "en-GB"
        ]
      }
    },
    "webExtension": {
      "locales": ["$USER_LOCALE"]
    }
  }]
}

Will report either [en-US] or [en-GB] as the webExtension.locales property depending on the user’s locale.

Since the special string is replaced, custom folder names can be searched for by adding the keyword in between a consistent prefix/suffix.

For example, if webExtension.locales was ["example-$USER_LOCALE"], the locale generator will generate locale names in the form of example-en-US and example-en-GB.

Note: Prior to Firefox 100.0, $USER_LOCALE used an exact match. In Firefox 100.0 the replacement was updated to use a standard string replacement.

From Firefox 98.0.1 and 97.7.1esr, "$USER_LOCALE" may also be used in the telemetryId field.

$USER_REGION

This can be used in the same situations as "$USER_LOCALE", instead replacing webExtension.locale with a string that uses the users region.

{
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
    },
    "webExtension": {
      "locales": ["foo-$USER_REGION"]
    }
  }]
}

In this example, if the user’s region is fr, the webExtension.locale will be foo-fr, and the code will look for the messages.json in the foo-fr folder of the _locales folder for this extension.

Note: "$USER_REGION" was added in Firefox 98.0.1 and 97.7.1esr and used an exact match. In Firefox 100.0 the replacement was updated to use a standard string replacement.

“default”

You can specify "default" as a region in the configuration if the engine is to be included when we do not know the user’s region.

“override”

The "override" field can be set to true if you want a section to only override otherwise included engines. "override" will only work for sections which apply to distributions or experiments. The experiment case was added in Firefox 81.

Starting with Firefox 96, "override" sections may include included and excluded information which will be applied accordingly. If they are not supplied, then the override section will be applied to everywhere.

Example:

{
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [{
    // Complicated and lengthy inclusion rules
  }, {
    "override": true,
    "application": { "distributions": ["mydistrocode"]},
    "params": {
      "searchUrlGetParams": [
        { "name": "custom", "value": "foobar" }
      ]
    }
  }]
}

Application Scoping

An engine configuration may be scoped to a particular application.

Name

One or more application names may be specified. Currently the only application type supported is firefox. If an application name is specified, then it must be matched for the section to apply. If there are no application names specified, then the section will match any consumer of the configuration.

In the following example, web@ext would be included on any consumer of the configuration, but web1@ext would only be included on Firefox desktop.

{
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
      "application": {
        "name": []
      }
    }
  ]}
},
{
  "webExtension": {
    "id": "web1@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
      "application": {
        "name": ["firefox"]
      }
    }
  ]}
}

Channel

One or more channels may be specified in an array to restrict a configuration to just those channels. The current known channels are:

default: Self-builds of Firefox, or possibly some self-distributed versions.

nightly: Firefox Nightly builds.

aurora: Firefox Developer Edition

beta: Firefox Beta

release: The main Firefox release channel.

esr: The ESR Channel. This will also match versions of Firefox where the displayed version number includes esr. We do this to include Linux distributions and other manual builds of ESR.

In the following example, web@ext would be set as default on the default channel only, whereas web1@ext would be set as default on release and esr channels.

{
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
      "default": "yes",
      "application": {
        "channel": ["default"]
      }
    }
  ]}
},
{
  "webExtension": {
    "id": "web1@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
      "default": "yes",
      "application": {
        "channel": ["release", "esr"]
      }
    }
  ]}
}

Distributions

Distributions may be specified to be included or excluded in an appliesTo section. The distributions field in the application section is an array of distribution identifiers. The identifiers match those supplied by the distribution.id preference.

In the following, web@ext would be included in only the cake distribution. web1@ext would be excluded from the apples distribution but included in the main desktop application, and all other distributions.

{
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
      "application": {
        "distributions": ["cake"]
      }
    }
  ]}
},
{
  "webExtension": {
    "id": "web1@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
      "application": {
        "excludedDistributions": ["apples"]
      }
    }
  ]}
}

Version

Minimum and Maximum versions may be specified to restrict a configuration to specific ranges. These may be open-ended. Version comparison is performed using the version comparator.

Note: comparison against maxVersion is a less-than comparison. The maxVersion won’t be matched directly.

In the following example, web@ext would be included for any version after 72.0a1, whereas web1@ext would be included only between 68.0a1 and 71.x version.

{
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
      "application": {
        "minVersion": "72.0a1"
      }
    }
  ]}
},
{
  "webExtension": {
    "id": "web1@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
      "default": "yes",
      "application": {
        "minVersion": "68.0a1"
        "maxVersion": "72.0a1"
      }
    }
  ]}
}

Experiments

We can run experiments by giving sections within appliesTo a experiment value, the Search Service can then optionally pass in a matching experiment value to match those sections.

Sections which have a experiment will not be used unless a matching experiment has been passed in, for example:

{
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
    },
    "experiment": "nov-16",
    "webExtension": {
      "id": "web-experimental@ext"
    }
  }, {
    "included": {
      "everywhere": true
    },
    "webExtension": {
      "id": "web-gb@ext"
    }
  }]
}

Engine Defaults

An engine may be specified as the default for one of two purposes:

normal browsing mode,
private browsing mode.

If there is no engine specified for private browsing mode for a particular region/locale pair, then the normal mode engine is used.

If the instance of the application does not support a separate private browsing mode engine, then it will only use the normal mode engine.

An engine may or may not be default for particular regions/locales. The default property is a tri-state value with states of yes, yes-if-no-other and no. Here’s an example of how they apply:

{
  "webExtension": {
    "id": "engine1@ext"
  },
  "appliesTo": [{
    "included": {
      "region": "us"
    },
    "default": "yes"
  }, {
    "excluded": {
      "region": "us"
    },
    "default": "yes-if-no-other"
  }]
},
{
  "webExtension": {
    "id": "engine2@ext"
  },
  "appliesTo": [{
    "included": {
      "region": "gb"
    },
    "default": "yes"
  }]
},
  "webExtension": {
    "id": "engine3@ext"
  },
  "default": "no"
  "appliesTo": [{
    "included": {
      "everywhere": true
    },
  }]
},
{
  "webExtension": {
    "id": "engine4@ext"
  },
  "defaultPrivate": "yes",
  "appliesTo": [{
    "included": {
      "region": "fr"
    }
  }]
}

In this example, for normal mode:

engine1@ext is default in the US region, and all other regions except for GB

engine2@ext is default in only the GB region

engine3@ext and engine4 are never default anywhere

In private browsing mode:

engine1@ext is default in the US region, and all other regions except for GB and FR

engine2@ext is default in only the GB region

engine3@ext is never default anywhere

engine4@ext is default in the FR region.

Engine Ordering

The orderHint field indicates the suggested ordering of an engine relative to other engines when displayed to the user, unless the user has customized their ordering.

The default ordering of engines is based on a combination of if the engine is default, and the orderHint fields. The ordering is structured as follows:

Default engine in normal mode
Default engine in private browsing mode (if different from the normal mode engine)
Other engines in order from the highest orderHint to the lowest.

Example:

{
  "webExtension": {
    "id": "engine1@ext"
  },
  "orderHint": 2000,
  "default": "no",
},
{
  "webExtension": {
    "id": "engine2@ext"
  },
  "orderHint": 1000,
  "default": "yes"
},
{
  "webExtension": {
    "id": "engine3@ext"
  },
  "orderHint": 500,
  "default": "no"
}

This would result in the order: engine2@ext, engine1@ext, engine3@ext.