path: root/toolkit/components/search/docs/SearchConfigurationSchema.rst

===========================
Search Configuration Schema
===========================

This document outlines the details of the `search-config-v2`_ 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, an object with a ``data`` property and value
as an array containing ``engine``, ``defaultEngines``, and ``engineOrders``
record types:

.. code-block:: js

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

Environment
===========
An ``environment`` property is contained within each of the record types and is
used to determine where some, or all, of that record is applied to according to
the user's detected environment. There are many different properties in ``environment``.
These may be used individually or together to build up a match. Here is the list
of those properties:

``allRegionsAndLocales``
  - ``"environment": { "allRegionsAndLocales": true }``
  - Indicates that this section applies to all regions and locales. May be
    modified by excludedRegions/excludedLocales.

``applications``
  - ``"environment": { "applications": ["firefox"] }``
  - This property specifies the applications the record would be applied to.
  - Some applications we support are ``firefox``, ``firefox-android``, ``firefox-ios``,
    ``focus-android``, and ``focus-ios``.

``channels``
  - ``"environment": { "channels": ["default"] }``
  - One or more channels may be specified in an array to restrict a configuration
    to just those channels. The following is a list of the channels:

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

``distributions``
  - ``"environment": { "distributions": ["distribution-name"] }``
  - An array of distribution identifiers that the record object applies to.
  - The identifiers match those supplied by the ``distribution.id`` preference.

``excludedDistributions``
  - ``"environment": { "distributions": ["distribution-excluded"] }``
  - An array of distribution identifiers that the record object does not apply to.

``excludedLocales``
  - ``"environment": { "excludedLocales": ["de"] }``
  - An array of locales that this section should be excluded from.

``excludedRegions``
  - ``"environment": { "excludedRegions": ["ca"] }``
  - An array of regions that this section should be excluded from.

``experiment``
  - ``"environment": { "experiment": "experimental" }``
  - Experiments can be run by giving a value to the ``experiment`` property.
  - The experiment value should also be supplied to the ``experiment`` property
    of the ``searchConfiguration`` feature on Nimbus.

``locales``
  - ``"environment": { "locales": ["en-US"] }``
  - An array of locales that this section applies to.

``regions``
  - ``"environment": { "regions": ["ca"] }``
  - An array of regions that this section applies to.
  - ``"unknown"`` may be used to apply to situations where we have not been able
    to detect the user's region. However, this is not currently expected to be used.

``maxVersion`` and ``minVersion``
  - 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.
  - ``"environment": { "minVersion": "72.0a1" }`` Indicates the record object
    will be included for any version after 72.0a1.
  - ``"environment": { "minVersion": "68.0a1", "maxVersion": "72.0a1" }``
    Indicates the record object would be included only between 68.0a1 and 71.x
    version.

Engine Objects
==============

Each engine object represents a search engine that may be presented to a user.
Each engine object is treated as a separate engine within the application, with
independent settings.

.. code-block:: js

    {
      "base": {
        "classification": "general"
        "name": "engine1 name",
        "partnerCode": "bar",
        "urls": {
          "search": {
            "base": "https://www.example.com",
            "params": [
              {
                "name": "code",
                "value": "{partnerCode}"
              }
            ],
            "searchTermParamName": "q"
          },
        },
      },
      "identifier": "engine1",
      "recordType": "engine",
      "variants": [
        {
          "environment": { "allRegionsAndLocales": true }
        }
      ]
    }

The required **top-level** properties are:

- ``base`` Defines the base details for the engine. The required base properties
  are ``classification``, ``name``, and ``urls``.

    - The ``urls`` may be different types of  urls. These various types include
      ``search``, ``suggestions``, and ``trending`` urls. The url property contains
      the base url and any query string params to build the complete url. If
      ``engine1`` is used to search ``kitten``, the search url will be constructed
      as ``https://www.example.com/?code=bar&q=kitten``. Notice the ``partnerCode``
      from the base is inserted into parameters ``{partnerCode}`` value of the search url.
- ``identifier`` Identifies the search engine and is used internally to set the telemetry id.
- ``recordType`` The type of record the object is. Always ``engine`` for engine
  objects.
- ``variants`` Specifies the environment the engine is included in, which details
  the region, locale, and other environment properties.

Engine Variants
===============
A engine may be available only to users located in specific regions or with
certain locales. For example, when the ``environment`` section of variants specify
locales and regions:

.. code-block:: js

    "variants": [
      {
        "environment": { "locales": ["en-US"], "regions": ["US"] }
      }
    ]

In this case users identified as being in the ``en-US`` locale and ``US`` region
would be able to have the engine available.

**Multiple Variants**

When there are more than one variant the last matching variant will be applied.

.. code-block:: js

  "variants": [
    {
      "environment": { "locales": ["en-US"] }
      "partnerCode": "bar"
    },
    {
      "environment": { "locales": ["en-US"], "regions": ["US"]}
      "partnerCode": "foo"
    },
  ]

In this case users identified in ``en-US`` locale and ``US`` region  matched
both the variants. Users in ``en-US`` locale and ``US`` region matched the
first variant because it has ``en-US`` locales and when regions is not specified,
it means all regions are included. Then it matched the second variant because it matched
``en-US`` locale and ``US`` region. The result will be that for this user the
partner code will have value ``foo``.

Engine Subvariants
==================
Nested within ``variants`` may be an array of ``subVariants``. Subvariants
contain the same properties as variants except the ``subVariants`` property. The
purpose of subvariants is for the combination of environment properties from the
last matched subvariant and the top level variant.

.. code-block:: js

    "variants": [
      {
        "environment": { "regions": ["US", "CA", "GB"] }
        "subVariants": [
          {
            "environment": { "channels": [ "esr"] },
            "partnerCode": "bar",
          },
        ]
      }
    ]

In this case users identified as being in ``US`` region and ``esr`` channel
would match the subvariant and would be able to have the engine available with
partner code ``bar`` applied.

**Multiple Subvariants**

When there are more than one subvariant the last matching subvariant will be
applied.

.. code-block:: js

  "variants": [
    {
      "environment": { "regions": ["US", "CA", "GB"] }
      "subVariants": [
        {
          "environment": { "channels": [ "esr"] },
          "partnerCode": "bar",
        },
        {
          "environment": { "channels": [ "esr"], "locales": ["fr"] },
          "partnerCode": "foo",
        }
      ]
    }
  ]

In this case users identified in ``US`` region, ``fr`` locale, and ``esr`` channel
matched both the subvariants. It matched the first subvariant because the first
environment has ``US`` region from the top-level variant, ``esr`` channel, and
all locales. Then it matched the second variant because the second environment
has ``US`` region from top-level variant, ``fr`` locale, and ``esr`` channel.
The user will receive the last matched subvariant with partner code ``foo``.

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
``defaultEngines`` record is structured to provide ``globalDefault`` and
``globalDefaultPrivate`` properties, these properties define the user's engine
if there are no ``specificDefaults`` sections that match the user's environment.
The ``specificDefaults`` sections can define different engines that match with
specific user environments.

.. code-block:: js

    {
      "globalDefault": "engine1",
      "globalDefaultPrivate": "engine1",
      "recordType": "defaultEngines",
      "specificDefaults": [
        {
          "default": "engine2",
          "defaultPrivate": "engine3"
          "environment": {
            "locales": [
              "en-CA"
            ],
            "regions": [
              "CA"
            ]
          },
        }
      ]
    }


In normal mode:

    - engine1 is default for all regions except for region CA locale en-CA
    - engine2 is default in only the CA region and locale en-CA

In private browsing mode:

    - engine1 is private default for all regions except for region CA locale en-CA
    - engine3 is private default in only the CA region and locale en-CA

Engine Ordering
===============

The ``engineOrders`` record type indicates the suggested ordering of an engine
relative to other engines when displayed to the user, unless the user has
customized their ordering. The ordering is listed in the ``order`` property, an
ordered array with the first engine being at the lowest index.

If there is no matching order for the user's environment, then this order applies:

#. Default Engine
#. Default Private Engine (if any)
#. Other engines in alphabetical order.

Example:

.. code-block:: js

    {
      "orders": [
        {
          "environment": {
            "distributions": [
              "distro"
            ]
          },
          "order": [
            "c-engine",
            "b-engine",
            "a-engine",
          ]
        }
      ]
      "recordType": "engineOrders",
    }

This would result in the order: ``c-engine``, ``b-engine``, ``a-engine`` for the
distribution ``distro``.

.. _schema itself: https://searchfox.org/mozilla-central/source/toolkit/components/search/schema/
.. _the version comparator: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/version/format
.. _search-config-v2: https://searchfox.org/mozilla-central/source/services/settings/dumps/main/search-config-v2.json