Overview

XML data feeds

Cognito Search is filled from XML data feeds that you host and we fetch on a schedule. Each feed is a plain XML document at a public URL. You register it once as a source in the admin panel (Instance → Sources), choosing its type, and from then on every import re-fetches that URL, validates it, and rebuilds the search index for that source.

There are four source types, each with its own fixed XML structure:

Type	Root element	Item element	What it holds
Products	`<items>`	`<item>`	E-shop products (the main searchable catalog).
Articles	`<articles>`	`<article>`	Blog posts, guides, help articles.
Categories	`<categories>`	`<category>`	Category pages, and the link targets for the
			category names used by products and articles.
Brands	`<brands>`	`<brand>`	Brand pages, and the link targets for product
			brand names.

One source is exactly one type. To index both products and articles, create two sources. See the per-type pages in the sidebar for the full element reference of each.

Feed requirements

Encoding: UTF-8. An <?xml version="1.0" encoding="UTF-8"?> declaration is recommended but optional — it is normalized on import.
Validation: every feed is validated against the DTD for its type before anything is indexed. The DTD fixes both which elements are allowed and the order they must appear in. A feed that does not conform fails at the validating stage and the previous index is kept.
Element order matters. The DTDs declare each item's children as an ordered sequence. Emit the elements in the documented order, or validation fails — even if every element is otherwise correct.
HTML content (for example an article annotation or a product description) should be wrapped in a CDATA section so the markup does not break XML parsing:
```
<annotation><![CDATA[<p>Rich <strong>HTML</strong> here.</p>]]></annotation>
```

How an import runs

Each import is recorded as a job you can follow under Instance → Sources → (source) → Jobs. A job moves through these stages:

pending → fetching → validating → parsing → indexing → completed

If any stage fails the job ends as failed, the stage is recorded, and the previously indexed data is left untouched — a broken feed never empties your search results.

Shared concepts

A few elements behave the same way across types. They are documented in full on each type page, but the cross-cutting rules are worth stating once.

Images: `image_link_s`, `image_link_m`, `image_link_l`

Small, medium, and large image URLs. All optional, on every type. They are stored and returned with results but are not searched. Provide whichever sizes you have; the widget and APIs pick the best available.

Categories and the `primary` flag

Products and articles can carry one or more <category> elements:

<category primary="true">Pain &amp; fever | OTC medicines</category>
<category>Health supplements</category>

An item may have any number of categories.
The optional primary attribute (true | false, default false) marks the main category. If you mark none as primary, the first category is treated as primary automatically.

Linking names to URLs (cross-source enrichment)

The text inside a product/article <category> and a product <brand> is just a name — it carries no URL of its own. To turn those names into links, configure the matching Categories and Brands sources on the same instance. On every import the names are resolved against them:

A <category> value is matched against the hierarchy of each entry in your Categories feeds. On a match, that category's url is attached.
A product <brand> value is matched by name against your Brands feeds. On a match, that brand's url is attached.

Matching is on the exact text, so a product's category string must equal the category's hierarchy string verbatim (whitespace and separators included). When no Categories/Brands source is configured, or no entry matches, the name is still indexed — only the resolved URL is left empty.