Webmaster
How Yandex indexes sites
A site on search results page

Form description

Attention! New schema cannot be added for now. In the following months, we’ll be doing more experiments and developments about interactive answers. Our team is working on more efficient ideas. Stay tuned for updates.

Websites with their own search or page classification (such as bulletin boards or booking services) can display their own search filters in the site's snippets in Yandex search results. A user can select the desired filter values to go directly to the appropriate search results on the website.

To create this type of form, the addresses of pages with search results must be directly dependent on the values of the search filters. When you have submitted a form description and search parameters, Yandex can display the form in search output and generate the exact addresses of your web pages.

XML description placement

You can provide Yandex with the XML file with form description several ways:

  • make a form description using Open Graph Protocol;

  • make a form description using Schema.org;

  • upload an XML file on the form editor page.

Form descriptions using Open Graph Protocol

OGP fields make it possible to refer to the forms' XML files located on the page, as well as set the default values for these forms. You can test the markup in the Webmaster validator.

Several form descriptions can be made for each page. Each form description should start by specifying the OGP field ya:interaction.

An example of a description of two forms:

<!--The ya:interaction field in the form description should apply the value "XML_FORM".-->
<meta property="ya:interaction" content="XML_FORM" />

<!--The field for the link to the XML file with the form description.-->
<meta property="ya:interaction:url" content="http://example.com/my_xml_url.xml" />

<!--Default value specification block. The field ya:interaction:property contains the form element's name,
    the field ya:interaction:property:default_value is the value which should be set for each element.-->
<meta property="ya:interaction:property" content="property_name" />
<meta property="ya:interaction:property:default_value" content="property_default_value" />

<!--The default value block for each form element.-->
<meta property="ya:interaction:property" content="property_2_name" />
<meta property="ya:interaction:property:default_value" content="property_2_default_value" />

<!--The description block for the second form must be situated after all information belonging to the first form.-->
<meta property="ya:interaction" content="XML_FORM" />
<meta property="ya:interaction:url" content="http://example.com/my_xml_url_2.xml" />

Form description using Schema.org

An extension for standard Schema.org supported by Yandex makes it possible to refer to XML files of forms located on the page, as well as to specify the default values for these forms. Soon you will be able to test the markup Schema.org in JSON-LD form using the Webmaster validator.

Several form descriptions can be made for each page. Each form description should conclude in a separate script element. The syntax JSON-LD is used for description.

An example of a description of two forms:

<script type="application/ld+json"> {

     <!--Mandatory field,  it indicates the use types of Schema.org data in the marking.-->
     "@context":"http://schema.org",

     <!--Mandatory field. Indicates the kind of Schema.org data the describes the forms.-->
     "@type" : "WebFormHandler",

     <!--Link to XML form description.-->
     "specificationUrl" : "http://example.com/my_xml_url_1.xml",

     <!--Default value block.
         @type — indicates the type of Schema.org data that describes the form's properties.
         name — property name.
         defaultValue — default value for the specified field.-->
     "defaultProperty" : [
         {
             "@type" : "FormProperty",
             "name" : "property_name",
             "defaultValue" : "property_def_value"
         },

         <!--Second default value.-->
         {
             "@type" : "FormProperty",
             "name" : "property_2_name",
             "defaultValue" : "property_2_def_value"
         }
     ]
}
</script>

<!--Second form description.-->
<script type="application/ld+json"> {
     "@context":"http://schema.org",
     "@type" : "WebFormHandler",
     "specificationUrl" : "http://example.com/my_xml_url_2.xml"
}
</script>

Form description language

The form description must be created as an XML file in UTF-8 encoding:

<?xml version="1.0" encoding="utf-8"?>

Use <site> as the root element.

The file should contain three parts:

General description

Description elements:

<!--Root element, XML schema and namespace declaration.-->
<site xmlns="http://interactive-answers.webmaster.yandex.ru/schemas/site/0.0.1"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://interactive-answers.webmaster.yandex.ru/schemas/site-0.0.1.xsd">

  <!--Short name of the site, used in the form title.-->
  <title>Code Search · GitHub</title>

  <!--Link to be used if URL cannot be built for given set of selected filters.-->
  <rootUrl>https://github.com/search</rootUrl>

  <!--Protocol for the page address. Only the values "HTTP" and "HTTPS" are supported. Optional element;
   the HTTP protocol is used by default.-->
  <protocol>HTTPS</protocol>

  <!--Short site description. The maximum length of text that will be displayed is 200 characters.-->
  <description>Search code on more than 6.5M repositories</description>

Structure of page URLs

A precise URL structure is necessary so that Yandex can redirect the user from the filled-in form to the appropriate page on your website. You can present any address on the site as http(s)://URL?params, where the URL is the page's static address and params is a set of CFI parameters. Here the URL structure is understood as a description of the parts of the static address.

The description of the structure of static addresses must be put in the <resource> element.

The fixed parts of the static address (such as a second-level domain) are described in the <fixed> elements. The variable parts of the URL are described using the <placeholder> elements. The sequence of the parts is determined by how the elements are nested; the element describing the following part must be nested inside the element with a description of the previous one.

The parts of the URL should be further defined using attributes:

  • name. A permanent part of the URL for the <fixed> element, or the name of a filter for the <placeholder> element. This attribute is mandatory for every element.

  • terminal. Flags that the URL is well-formed if this part of the address comes last. Optional attribute.

    Acceptable values: true (default) or false.

  • separator. The separator between this part of the URL and the next one. Optional attribute; by default, a slash character (/) is used as a separator.

  • required. Flags that this part of the URL is required (supported only for the <placeholder> element). Optional attribute.

    Acceptable values: true or false.

Example of several static addresses for an automobile site:

  • ford.example.com

  • ford.example.com/fiesta

  • ford.example.com/focus

  • ford.example.com/dealers/moscow

  • ford.example.com/dealers/berlin

  • nissan.example.com

This set of addresses can be described by the following XML code:

<!-- Root element of address structures -->
<resource>

  <!-- The first part of the URL is the subdomain with a filter for car makes (Ford, Nissan, and so on).
   The default separator (slash) can't be used here, so we set a dot
   as the value for the "separator" attribute.-->
  <placeholder name="make" terminal="false" separator=".">

    <!--The second part of the URL is the site domain, which is always the same.-->
    <fixed name="example.com">

      <!--Top-level directory with a filter for car models.-->
      <placeholder name="model">

        <!--Nested directory with a filter for the generation of model.-->
        <placeholder name="generation" />
      </placeholder>

      <!--Top-level directory for information about dealers for this make.-->
      <fixed name="dealers">

        <!--Nested directory with a filter for the city to search for a dealer in.-->
        <placeholder name="city" />
      </fixed>
    </fixed>
  </placeholder>
</resource>

Filters and the form interface

Each filter that can be used in the form must be defined by choosing the appropriate form element, specifying a set of values, and so on. The description of all the filters must be put in the <filters> element.

How to process the filter and the filter name must be set in the general filter description.

The search output forms currently support the following types of filters:

  • dropDown — A drop-down list similar to the HTML <select> tag.

  • checkBox — A checkbox similar to <input type="checkbox">.

  • rangeFilter — A range filter (a minimum value — maximum value pair).

  • textBox — A text field similar to <input type="text">.

  • geo is the location selection (the analog of the <select> HTML element).

  • rangeGeo is the route selection (the analog of two <select> HTML elements).

  • date is the date selection using the calendar.

  • rangeDate indicates the date interval using the calendar.

  • constant is a permanent parameter (the analog of the <input type="hidden"> HTML element).

A filter can also be dependent: this type of filter can only be used after selecting a particular value in the parent filter.

The current set of filter types will be expanded over time.

General filter description

For each filter, you must specify the name and processing rules (how the filter value is used when forming the URL). This information must be included in the <description> element.

The filter name is set in the mandatory caption attribute.

Filter processing rules — how the selected value affects the resulting URL. These rules are described by elements contained in <description>:

  • <setParameter> — Sets the selected value in the CGI parameter that is specified in the name attribute.

  • <modifyResource> — Substitutes the selected value for the variable part of the URL whose name is specified in the placeholder attribute.

Values of the filters are:

  • for <rangeFilter> — The selected lower or upper end of the range.

  • for <dropDown> — The value of the key attribute for the selected <dropDownValue>

  • for <checkBox> — The value of the key attribute for the <checked> or <unchecked>.

  • for <textBox> — The actual value of the text field.

  • for <geo> — The value of the key attribute for the selected <geoValue>

  • for <rangeGeo> — The value of the key attributes for the selected <geoValue>

  • for <date> — the selected date in the specified format;

  • for <rangeDate> — the selected dates in the specified format.

For range filters (<rangeFilter>), two processing rules must be set: one for the lower end of the range, and one for the upper end. For all the other filter types, only one rule is allowed.

If necessary, we are prepared to add more types of filter behavior.

The way to set the possible values of the filter depends on its type. The supported filter types are described below:

A drop-down list should be used when the filter value is limited to a pre-defined set of values. For example, a drop-down list might be a list of automobile makes or models.

Example of filter design with a drop-down list:

<!-- Default value set by the default attribute.-->
<dropDown default="808080" >
  <!--label for the dropdown list set in the caption attribute value.-->
  <description caption="Pant color">

    <!--The name of the CGI parameter set by the filter is specified in the name attribute.-->
    <setParameter name="color" />
  </description>

  <!--Each value of the dropdown list is set as a separate dropDownValue element.
   At least one such element is mandatory.
   The filter value is the value of the "key" attribute for the selected point in the list.-->
  <dropDownValue key="808080" caption="gray"/>
  <dropDownValue key="ffff00" caption="yellow" />
  <dropDownValue key="dc143c" caption="crimson" />
</dropDown>

Checkbox

A checkbox should be used for a pair of opposite values. For example, when searching for apps, you can clear the "free" checkbox to search for fee-based apps.

Example of defining a checkbox filter:

<checkBox>
  <!--The filter label is set in the value of the "caption" attribute.-->
  <description caption="free">

    <!--The name of the CGI parameter corresponding to the filter is set in the "name" attribute.-->
    <setParameter name="price" />
  </description>

  <!--The filter value is the value of the "key" attribute. This element is mandatory for a checkbox filter.
    The checkbox is selected by default, since the "default" attribute is set with the value "true".-->
    <checked key="free" default="true"/>

    <!--Optional element lets you also specify the filter value for the cleared checkbox.-->
    <unchecked key="paid" />
</checkBox>

When a user selects the checkbox, the CGI parameter price="free" is added to the URL, and when the user clears the checkbox, the parameter price="paid" is added to the URL, thus selecting free or fee-based apps, respectively.

To let the user turn off filtering in this example, we should remove the key attribute for the <unchecked> element, or remove the element entirely. In this case, when the checkbox is cleared, the price CGI parameter will not be included in the resulting URL.

Range filter

This filter should be used for restricting numeric parameters of the search. It cannot have dependent filters.

The filter can have two values simultaneously if the upper and lower ends of the range are specified. Accordingly, the <description> section must describe how to process both values.

Example of defining a price filter:

<!-- Attributes:
    min — lower end of the range, mandatory attribute.
    max — upper end of the range, mandatory attribute.
    step — interval for changing a value, used for rounding off entered numbers.
     Optional attribute (by default, "step" is set to 1).
    unit — measurement unit, optional attribute (displayed on the entry form). -->
<rangeFilter min="0" max="10000" step="10" unit="USD">

  <!--The label for the range is set in the "caption" attribute.-->
  <description caption="Price">

    <!--The range filter must add both the minimum and maximum values to the URL.-->
    <setParameter name="min_price" />
    <setParameter name="max_price" />
  </description>
</rangeFilter>

Text box

This filter should be used if your website has full-text search; the text field serves as a search string.

The value of the filter is the string from the text field (without changes).

The form can automatically fill in the text field with the words from the search query. The way to fill it in is set by the filter's type attribute (as an example, let's assume the query is being parsed for an automobile site with filters for make, model, and type of transmission):

  • Insert the Yandex search query in the field in its original form (type="WholeQuery"). Example: [buy opel astra in moscow automatic cheap].

  • Insert only the query words that Yandex could not match to a filter (type="AllUnparsed"). Example: [buy in moscow cheap].

  • Insert the longest continuous sequence of unparsed words (type="LongestUnparsed"). Example: [in moscow].

  • Insert the first sequence of unparsed words (type="LeftUnparsed"). Example: [buy].

  • Insert the last sequence of unparsed words (type="RightUnparsed"). Example: [cheap].

  • Do not fill in the field automatically (type="NoFilling").

<!--The "type" attribute specifies that by default, the text field must be filled in with
     the longest continuous sequence of query words that do not match the filters.-->
<textBox type="LongestUnparsed">

  <!--The label for the text field is set in the "caption" attribute.-->
  <description caption="What are you looking for?">

    <!--The name of the CGI parameter for passing the contents of the text field set is set in the "name" attribute.-->
    <setParameter name="q" />
  </description>
</textBox>

Location

It is recommended to use the filter if you want to give users the ability to select their country, city, or district.

An example of a filter's definition with a selected city:

<!-- The useUserRegion="true" attribute indicates that the user's region must be used by default
     (as Yandex determined it to be).
     You can clearly set the default value by using the "default" attribute. -->
<geo useUserRegion="true" default="MOW">
  <description caption="Place of birth">
    <setParameter name="birth_place"/>
  </description>
  <geoValue key="MOW" caption="Moscow"/>
  <geoValue key="LED" caption="Saint Petersburg"/>
  <geoValue key="SVX" caption="Yekaterinburg"/>
  <geoValue key="KZN" caption="Kazan"/>
  <geoValue key="UFA" caption="Ufa"/>
</geo>

Route

It is recommended to use the filter if you want to allow users to select a pair of geographical objects (for example, cities of departure and arrival for a flight).

An example of a filter's appearance with a selected route:

<!--The value of the useUserRegion attribute indicates that the user's location has been determined by Yandex,
     it's recommended to set the default of the beginning and end of a route in the following way:
       - "from" — consider the location as the beginning of the user's route;
       - "to" — consider the location as the end of the user's route.
     You can clearly set the default values by using the defaultFrom and defaultTo attributes.
     Selection field labels are set by the "captionFrom" and "captionTo" attributes' values.-->
<rangeGeo useUserRegion="from" defaultFrom="MOW" defaultTo="UFA"  captionFrom="From" captionTo="To">
  <!--The general route selection label is set in the "caption" attribute value.-->
  <description caption="Route">
    <modifyResource placeholder="s0from"/>
    <modifyResource placeholder="s0to"/>
  </description>

  <!--You must indicate at least one city for selection. Each point on the list appears
      as a separate geoValue element.
      The filter value is the "key" attribute's value for the selected point on the list.-->
  <geoValue key="MOW" caption="Moscow"/>
  <geoValue key="LED" caption="Saint Petersburg"/>
  <geoValue key="SVX" caption="Yekaterinburg"/>
  <geoValue key="KZN" caption="Kazan"/>
  <geoValue key="UFA" caption="Ufa"/>
</rangeGeo>

Date

It is recommended to use the filter if you want to allow the user to select a specific date.

Example of defining a date filter:

<!--The date format (according to the standard ISO 8601) is shown in the "format" attribute value.
     The default date — the gap from the current date in days — is set in the "default" attribute value. -->
<date format="ddMMyyyy" default="1">
  <!--The date label is set in the "caption" attribute value.-->
  <description caption="Birthday">
    <setParameter name="date" />
  </description>
</date>

Date interval

It is recommended to use the filter if it is necessary to choose a pair of dates or a time interval.

An example of a filter's definition with a date interval:

<!--The format of every date (according to the standard ISO 8601) is shown in the "format" attribute value.
    Default values — the gap from the current date in days — are set using the attributes "defaultFrom"
    (start date) and "defaultTo" (end date).
    "captionFrom" and "captionTo" attribute's values are set by the first and second date labels.-->
<rangeDate format="ddMMyyyy" defaultFrom="1" defautTo="7" captionFrom="Departure date" captionTo="Arrival date">
  <!--The general date interval label is set in the "caption" attribute value.-->
  <description caption="Dates">
    <modifyResource placeholder="dateTo"/>
    <modifyResource placeholder="dateBack"/>
  </description>
</rangeDate>

Permanent parameter

Permanent parameters can be used if it is required to send a parameter that is not linked to any filter not specified by the user.

An example of a permanent parameter filter:

<!-- The following parameter is added in the search results _source=yandex -->
<constant key="_source">
  <description caption="Source mark">
    <setParameter name="yandex"/>
  </description>
</constant>

Dependent filters

A filter that should only be available when a certain value is set for a different filter can be made a dependent filter. Dependent filters should be fully described inside the corresponding value.

For example, a range of prices should only be available when the "free" checkbox is cleared. A <rangeFilter> is described inside the <unchecked> value for the filter with a checkbox:

<checkBox>
    <description caption="Free">
          <setParameter name="free" />
    </description>
    <checked key="1" />

    <!-- If the checkbox is unchecked, the nested range filter of prices is available.-->
    <unchecked>
        <rangeFilter min="0" max="50" step="1" unit="usd">
            <description caption="Price">
                <setParameter name="min_price" />
                <setParameter name="max_price" />
            </description>
        </rangeFilter>
    </unchecked>
</checkBox>

Dependent filters cannot be put in the descriptions for <rangeFilter> or <textBox>. In addition, the text field cannot be a dependent filter.

HTTP request methods

GET (default) or POST are able to used as an HTTP request method. You can indicate the request method for the whole form or separately for each parameter. A specifically indicated request method has higher priority than a method indicated for the whole form.

An example of a request method

<site xmlns="http://interactive-answers.webmaster.yandex.ru/schemas/site/0.0.1"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://interactive-answers.webmaster.yandex.ru/schemas/site-0.0.1.xsd">
  <rootUrl>http://example.com</rootUrl>
  <title>Example</title>
  <description>Ad space for the sale of dogs and cats, puppies and kittens</description>
  <!-- POST request method for the whole form. -->
  <requestMethod>POST</requestMethod>
  ...

  <filters>
    <checkBox>
      <description caption="kittens">
        <!-- The request method for a concrete  parameter is set in the "requestMethod" attribute. -->
        <setParameter name="is_young" requestMethod="GET"/>
      </description>
      <checked key="1"/>
    </checkBox>
  </filters>
</site>

Yandex.Metrica counter for form

By attaching a Yandex.Metrica counter to your form, you can analyze users actions. You can receive a counter's ID in the General tab on the counter's page.

Example of a counter:

<site xmlns="http://interactive-answers.webmaster.yandex.ru/schemas/site/0.0.1"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://interactive-answers.webmaster.yandex.ru/schemas/site-0.0.1.xsd">

  <title>Lease real estate without intermediaries</title>
  <!--Metrica counter identifier.-->
  <metricaCounterId>123452</metricaCounterId>
  ...
</site>
Rate this article
Thank you for your feedback!