# Configuring Schema.org markup in articles (JSON-LD, microdata)
Schema.org markup describes page content in a machine-readable form: what kind of document it is, what it is about, and when it was published and updated. Search engines use it for rich snippets, and AI services use it to understand and quote the article more accurately.

## What is JSON-LD

JSON-LD (JSON for Linked Data) is a format for writing Schema.org markup as a JSON object inside a `<script type="application/ld+json">` tag. The markup does not affect how the page looks. Google and Yandex recommend this format.

In Swarmica, the markup is set in the `jsonld` field on the **SEO** tab of the article editor, separately for each language. The help center wraps the value in the `<script>` tag itself, so enter only the JSON:

```json
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "How to configure an SMTP channel for email in Swarmica",
  "description": "Step-by-step setup of outgoing email via SMTP in Swarmica.",
  "inLanguage": "en",
  "datePublished": "2026-05-12",
  "dateModified": "2026-09-01",
  "image": "https://support.example.com/attachments/a/b/abc_a/smtp.png"
}
```

:::caution
The field value must be valid JSON, otherwise the article will not be saved.
:::

## What is microdata

Microdata is an alternative way to describe Schema.org data using the `itemscope`, `itemtype` and `itemprop` attributes directly in the page HTML.

The help center renders part of the microdata itself: the values of the `seo_description` and `seo_image` fields are duplicated in meta tags with the `itemprop` attribute. You do not need to add microdata to the article text: for articles to work and display correctly, it is not recommended to use any HTML inserts in them (see [Can an article be extended with custom HTML](https://support.swarmica.com/article/en/2043)). Use the `jsonld` field for your own markup.

## Schema.org types for knowledge base articles

| Type | When to use |
| --- | --- |
| `TechArticle` | The recommended type for most knowledge base articles: instructions, troubleshooting, settings descriptions. |
| `Article` | General articles that are not technical documentation: news, overviews. |
| `HowTo` | Step-by-step instructions with explicit steps (`step`). |
| `FAQPage` | The article contains a list of questions and answers written by your company. |
| `QAPage` | A page with one question and answers to it, including answers from users. |
| `BreadcrumbList` | Breadcrumbs: the path to the article through knowledge base categories. |
| `VideoObject` | The article contains a video. |

The `Organization` and `WebSite` types describe the company and the site as a whole, so there is no need to repeat them in every article. Add them once for the entire knowledge base portal: **Settings → General settings → Brand management → <Default brand> → Public knowledge base portal styles → HTML head code**.

Unlike the article `jsonld` field, this field requires the markup together with the `<script>` tag:

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "name": "Company name",
      "url": "https://example.com",
      "logo": "https://example.com/logo.png"
    },
    {
      "@type": "WebSite",
      "name": "Company knowledge base",
      "url": "https://support.example.com/help",
      "inLanguage": ["ru", "en"]
    }
  ]
}
</script>
```

:::tip
Search engines do not show rich snippets for every markup type. For example, Google has limited rich results for `FAQPage` and `HowTo`. Even so, such markup helps search engines and AI services understand the article structure.
:::

## TechArticle properties

| Property | Value |
| --- | --- |
| `headline` | The article title, up to 110 characters. |
| `description` | A short description; you can take it from `seo_description`. |
| `inLanguage` | The article language: `ru`, `en`. |
| `datePublished`, `dateModified` | Publication and last modification dates in ISO 8601 format. |
| `image` | The absolute address of an image from the article. |
| `about`, `keywords` | The product or topic of the article, keywords. |
| `author` | The article author (`Person`) or company (`Organization`). |

## Several objects in one article

To describe several entities — for example, an article and its breadcrumbs — use the `@graph` array:

```json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "TechArticle",
      "headline": "How to configure an SMTP channel for email in Swarmica",
      "inLanguage": "en"
    },
    {
      "@type": "BreadcrumbList",
      "itemListElement": [
        { "@type": "ListItem", "position": 1, "name": "Knowledge base", "item": "https://support.example.com/help" },
        { "@type": "ListItem", "position": 2, "name": "System settings", "item": "https://support.example.com/category/1" }
      ]
    }
  ]
}
```

An example of `FAQPage` markup:

```json
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Can I use a proxy other than SOCKS5 for Telegram?",
      "acceptedAnswer": { "@type": "Answer", "text": "No, only SOCKS5 is supported." }
    }
  ]
}
```

## Recommendations

*   The markup must match the visible article text. Do not add questions, answers or facts that are not on the page.
*   Use absolute addresses — with the protocol and domain — in JSON-LD.
*   Update `dateModified` when the article changes significantly.
*   Fill in the markup for each language of the article in the language of that locale.
*   After saving, check the markup with one of the tools below.

## Validation tools

*   [Schema Markup Validator](https://validator.schema.org/) — checks markup against the Schema.org vocabulary.
*   [Google Rich Results Test](https://search.google.com/test/rich-results) — shows which rich results the page may be eligible for in Google.
*   [Yandex Webmaster structured data validator](https://webmaster.yandex.ru/tools/microtest/) — checks markup for Yandex search.

You can pass the address of a published article to these tools or paste a code fragment.

## Related articles

*   [Configuring article SEO fields (Open Graph, JSON-LD)](https://support.swarmica.com/article/en/2146)
*   [Using AI agents for SEO/GEO/AEO optimization of the knowledge base](https://support.swarmica.com/article/en/2148)