#2147: 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:

{
  "@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"
}

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). Use the jsonld field for your own markup.

Schema.org types for knowledge base articles

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 → → Public knowledge base portal styles → HTML head code.

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

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

TechArticle properties

Several objects in one article

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

{
  "@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:

{
  "@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 — checks markup against the Schema.org vocabulary.
• Google Rich Results Test — shows which rich results the page may be eligible for in Google.
• Yandex Webmaster structured data validator — 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)
• Using AI agents for SEO/GEO/AEO optimization of the knowledge base