AI Metadata Specification
The set of <head> tags that tell AI search engines what your page is about — four critical fields that determine your metadata score, plus nine supplemental fields that improve context and social sharing.
Critical fields
The Analyzer evaluates four tags as critical. All four must be present for a pass status. Missing any one of them produces a warn; missing all four produces a fail.
| Field | Selector | Criticality | Purpose |
|---|---|---|---|
| Page title | title | Critical | Primary label used by AI engines to identify and cite the page |
| Meta description | meta[name="description"] | Critical | Plain-text summary used in AI-generated answers and search snippets |
| OG title | meta[property="og:title"] | Critical | Open Graph title — used by AI crawlers that parse OG data for page context |
| OG description | meta[property="og:description"] | Critical | Open Graph description — reinforces the meta description for OG-aware crawlers |
Why Open Graph tags are critical
Many AI crawlers parse Open Graph metadata in addition to standard HTML meta tags. A page with a
<title> and meta[name="description"] but no OG equivalents will still receive a warn from the Analyzer.Non-critical fields
The nine non-critical fields do not affect the CheckStatus result, but missing them is reported as low-severity issues. They improve how AI engines and social platforms represent your content.
| Field | Selector | Criticality | Purpose |
|---|---|---|---|
| Canonical URL | link[rel="canonical"] | Non-critical | Prevents duplicate-content issues by declaring the authoritative URL |
| Robots directive | meta[name="robots"] | Non-critical | Controls indexing and following behavior for all crawlers |
| OG URL | meta[property="og:url"] | Non-critical | Canonical URL for Open Graph — used when the page is shared or cited |
| OG type | meta[property="og:type"] | Non-critical | Content type hint (website, article, product) for OG-aware consumers |
| OG image | meta[property="og:image"] | Non-critical | Preview image used in social shares and AI-generated rich results |
| Twitter card | meta[name="twitter:card"] | Non-critical | Card format for Twitter/X previews (summary, summary_large_image, etc.) |
| Twitter title | meta[name="twitter:title"] | Non-critical | Title override for Twitter/X card display |
| Twitter description | meta[name="twitter:description"] | Non-critical | Description override for Twitter/X card display |
| Twitter image | meta[name="twitter:image"] | Non-critical | Image override for Twitter/X card display |
Complete example
The following <head> block includes all thirteen fields — four critical and nine non-critical — populated with realistic values.
index.html
<head>
<!-- Critical fields -->
<title>Widget Pro — Professional-Grade Widgets</title>
<meta name="description" content="Widget Pro is the fastest, most reliable widget for modern development teams. Free shipping on orders over $50." />
<meta property="og:title" content="Widget Pro — Professional-Grade Widgets" />
<meta property="og:description" content="Widget Pro is the fastest, most reliable widget for modern development teams. Free shipping on orders over $50." />
<!-- Non-critical fields -->
<link rel="canonical" href="https://example.com/products/widget-pro" />
<meta name="robots" content="index, follow" />
<meta property="og:url" content="https://example.com/products/widget-pro" />
<meta property="og:type" content="product" />
<meta property="og:image" content="https://example.com/images/widget-pro-og.jpg" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="Widget Pro — Professional-Grade Widgets" />
<meta name="twitter:description" content="The fastest, most reliable widget for modern development teams." />
<meta name="twitter:image" content="https://example.com/images/widget-pro-twitter.jpg" />
</head>Keep title and OG title in sync
The
<title> and meta[property="og:title"] values do not need to be identical, but they should describe the same page. Significant divergence can confuse AI engines that compare both fields.Analyzer checks
The checkMetadata function parses the homepage HTML using Cheerio and evaluates the presence of the four critical tags:
| Condition | Status | Recommendation code |
|---|---|---|
| All four critical tags present | pass | — |
| At least one critical tag present, but not all four | warn | COMPLETE_CRITICAL_METADATA |
| All four critical tags absent | fail | ADD_CRITICAL_METADATA |
| Empty or unparseable HTML | unknown | — |
Non-critical tag gaps are reported as low-severity issues and may trigger the IMPROVE_SUPPLEMENTAL_METADATA recommendation when the overall status is warn, but they do not change the CheckStatus value.
Common mistakes
- Missing OG tags on pages that have a title and description. A page with
<title>andmeta[name="description"]but nometa[property="og:title"]ormeta[property="og:description"]still returnswarn. All four critical tags must be present. - Empty content attributes. A tag like
<meta name="description" content="">is present in the DOM but has no value. The Analyzer treats an emptycontentattribute as absent and counts it as a missing field. - Duplicate tags with conflicting values. Some CMS plugins inject a second
<title>ormeta[name="description"]. Cheerio selects the first occurrence; if the first tag is empty and the second has content, the Analyzer will still report the field as missing. - Metadata injected only by JavaScript. The Analyzer fetches raw HTML before any client-side rendering. Tags added by React, Vue, or other frameworks after hydration are not visible to the checker. Use server-side rendering or static generation to ensure tags are present in the initial HTML response.
- No
<head>element. If the HTML response has no<head>element — for example, a bare JSON response or a redirect page — the Analyzer returnsunknownand cannot evaluate any metadata fields.