1. Two Consumers, Two Vocabularies#

The moment you paste a link into WeChat, Slack, or Discord and it turns into a card with an image, and the moment Google understands it as “an article published by someone on some date,” are two completely unrelated things.

They are driven by two different sets of tags, running in the hands of two different consumers:

Three things you must remember first:

1. og:* does not feed into Google’s rich results, and JSON-LD does not determine chat cards. You need to write both; neither can replace the other;
2. Crawlers do not execute JavaScript. What they get is HTML that “hasn’t run React.” Any meta tag injected client-side via JS effectively does not exist for these consumers;
3. Both sets of tags are a continuation of the same task—letting machines correctly understand what this page is without you having to explain it.

NOTE

Point 2 is the only thing og:* and JSON-LD have in common: they both require server-side rendering. This is also why client-side rendered (CSR) SPAs often appear as “a blank slate” on social platforms—it’s not that the tags are wrong, it’s that they haven’t been created yet at crawl time.

2. Open Graph: Four Required Properties, and a Bunch Mistaken for Required#

The Open Graph protocol (ogp.me) defines only four required properties:

1
<meta property="og:title" content="Article title" />
2
<meta property="og:type" content="article" />
3
<meta property="og:image" content="https://example.com/og/cover.jpg" />
4
<meta property="og:url" content="https://example.com/posts/foo" />

The rest—og:description, og:site_name, og:locale—are recommended but not required. Many people assume og:description is required—it isn’t, but it determines those two lines of summary on the card, and in practice you can’t afford to omit a single one.

og:type isn’t just decoration; it determines semantics: use website for homepages and landing pages, article for articles. Choosing the wrong value won’t throw an error—it will just cause consumers to process your page in the wrong form.

1
<meta property="og:image" content="https://example.com/og/cover.jpg" />
2
<meta property="og:image:width" content="1200" />
3
<meta property="og:image:height" content="630" />
4
<meta property="og:image:alt" content="Sample cover: a blue card with a title image" />

3. Three Silent Failures of og:image#

This section deserves its own discussion, because when og:image goes wrong, not a single error is thrown—the card just quietly gets uglier.

1
<!--Wrong: most consumers just drop this tag -->
2
<meta property="og:image" content="/og/cover.jpg" />
3

4
<!--Right: it must be an absolute URL -->
5
<meta property="og:image" content="https://example.com/og/cover.jpg" />

4. twitter:card: The Property Name Is name, Not property#

Twitter Card tags look a lot like Open Graph, but there’s one difference that’s easy to overlook:

1
<meta property="og:title" content="Article title" />
2

3
<!--Note this is name, not property -->
4
<meta name="twitter:card" content="summary_large_image" />
5
<meta name="twitter:title" content="Article title" />
6
<meta name="twitter:description" content="One-line summary" />
7
<meta name="twitter:image" content="https://example.com/og/cover.jpg" />

Two behaviors worth remembering:

• Falls back to og:* when missing. So if you only write Open Graph, X often still shows a card—but twitter:card itself has no og:* equivalent, and without it you won’t get a large card. That one line summary_large_image is the key to large cards;
• Images smaller than 300×157 are silently downgraded to small cards. Silent again—no warning, the card just gets smaller.

WARNING

X’s official Card Validator was shut down in 2022. The most reliable way to verify cards now is to actually send the link to yourself (or to a private chat) and see how it renders, rather than relying on tools. Facebook’s Sharing Debugger is still around, and it also refreshes WhatsApp’s cache—because WhatsApp’s preview cache lasts about 7 days, and you won’t see changes after editing og:image without refreshing.

5. Structured Data: Google Says “No Required Properties”#

Open Google’s Article structured data documentation, and the first thing you’ll see is a counterintuitive statement: no properties are required. Google’s wording is “add all applicable and recommended properties.”

But “no required properties” doesn’t mean “write whatever you want.” What really determines whether you get into rich results is this set:

@type must be one of Article, NewsArticle, or BlogPosting. Use JSON-LD format (Google explicitly recommends it), placed inside <script type="application/ld+json">.

One point worth clarifying: application/ld+json has both json and javascript in its name, but it is not an executable script—it’s just parsed data. So there’s no “needs JS enabled” problem, and it shouldn’t be treated as a script performance cost.

6. Generating Two Sets of Tags from One Source of Truth#

The most error-prone part of a real project is hand-copying the same piece of information into two places: og:title copies the title once, headline copies it again. Missing one spot won’t throw an error—it just leaves two sets of consumers seeing inconsistent worlds.

The right approach is to have them derive from the same data source. Taking this site’s Astro structure as an example, the article’s frontmatter is the single source of truth:

1
//Core logic of src/components/SeoHead.astro
2
const { title, description, published, tags, cover } = Astro.props
3
const site = Astro.site!          //site in astro.config.mjs
4

5
//Key: use new URL instead of string concatenation to guarantee an absolute URL
6
const abs = (path: string) => new URL(path, site).href
7

8
//Image dimensions are not hardcoded; they are derived from metadata known at build time
9
const coverUrl = abs(cover.url)

The Open Graph part:

1
<meta property="og:type" content="article" />
2
<meta property="og:title" content={title} />
3
<meta property="og:description" content={description} />
4
<meta property="og:url" content={canonicalUrl} />
5
<meta property="og:image" content={coverUrl} />
6
<meta property="og:image:width" content={String(cover.width)} />
7
<meta property="og:image:height" content={String(cover.height)} />
8
<meta property="og:image:alt" content={cover.alt} />
9

10
<meta name="twitter:card" content="summary_large_image" />
11
<meta name="twitter:image" content={coverUrl} />

For the structured data part, use @graph to extract the author and define it only once, with articles referencing it via @id—rather than repeatedly embedding a Person inside every object:

1
const jsonLd = {
2
  '@context': 'https://schema.org',
3
  '@graph': [
4
    {
5
      '@type': 'Person',
6
      '@id': `${site}#author`,
7
      name: authorName,
8
      url: site.href,
9
    },
10
    {
11
      '@type': 'BlogPosting',
12
      headline: title,
13
      description,
14
      image: [coverUrl],
15
      keywords: tags,
16
      author: { '@id': `${site}#author` },
17
      datePublished: published,        //Already ISO 8601
18
      dateModified: updated ?? published,
19
      mainEntityOfPage: { '@type': 'WebPage', '@id': canonicalUrl },
20
      inLanguage: 'zh-CN',
21
    },
22
  ],
23
}

1
<script is:inline type="application/ld+json" set:html={JSON.stringify(jsonLd)} />

WARNING

og:url should equal this page’s canonical URL, not “the URL the browser is currently on.” The two diverge in cases of pagination, trailing slashes, and tracking parameters, and when they diverge the card points to a non-canonical URL. In this site’s template there happen to be both a Astro.url and a separate canonicalUrl variable—if the former is being used here, it’s worth switching to the latter: make both fields point to the same place, and the possibility of conflict disappears.

7. Self-Check Before Going Live#

The script below makes no assumptions. It opens the real production page, then fetches the images itself and measures their dimensions: it only passes if the measured width and height match what’s declared in the meta.

1
// node scripts/check-og.mjs https://www.example.com/posts/foo
2
import { Buffer } from 'node:buffer'
3

4
const url = process.argv[2]
5
if (!url) {
6
  console.error('Usage: node scripts/check-og.mjs <page URL>')
7
  process.exit(2)
8
}
9

10
const html = await (await fetch(url)).text()
11

12
function parseMeta(head) {
13
  const tags = new Map()
14
  for (const [tag] of head.matchAll(/<meta\b[^>]*>/gi)) {
15
    const attrs = {}
16
    for (const [, key, , dq, sq] of tag.matchAll(
17
      /([\w:-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g,
18
    )) {
19
      attrs[key.toLowerCase()] = dq ?? sq ?? ''
20
    }
21
    const name = attrs.property || attrs.name
22
    if (name) tags.set(name, attrs.content ?? '')
23
  }
24
  return tags
25
}
26

27
//Parse only the header bytes: read IHDR for PNG, scan SOF segments for JPEG
28
async function measure(src) {
29
  const buf = Buffer.from(await (await fetch(src)).arrayBuffer())
30
  const PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
31
  if (buf.subarray(0, 8).equals(PNG)) {
32
    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) }
33
  }
34
  let i = 2
35
  while (i < buf.length - 9) {
36
    if (buf[i] !== 0xff) { i++; continue }
37
    const marker = buf[i + 1]
38
    if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker)) {
39
      return { height: buf.readUInt16BE(i + 5), width: buf.readUInt16BE(i + 7) }
40
    }
41
    i += 2 + buf.readUInt16BE(i + 2)
42
  }
43
  throw new Error('Not PNG or JPEG')
44
}
45

46
const meta = parseMeta(html.slice(0, html.indexOf('</head>')))
47
const fails = []
48
const check = (ok, msg) => { if (!ok) fails.push(msg) }
49

50
//1. Four required attributes
51
for (const key of ['og:title', 'og:type', 'og:image', 'og:url']) {
52
  check(meta.has(key), `Missing required property ${key}`)
53
}
54

55
//2. Image and page URLs must be absolute
56
for (const key of ['og:image', 'og:url']) {
57
  const value = meta.get(key)
58
  if (value) check(/^https?:\/\//.test(value), `${key} is not an absolute URL: ${value}`)
59
}
60

61
//3. The declared width and height must match the image's actual width and height
62
const src = meta.get('og:image')
63
if (src && /^https?:/.test(src)) {
64
  const real = await measure(src)
65
  const w = meta.get('og:image:width')
66
  const h = meta.get('og:image:height')
67
  if (w) check(Number(w) === real.width, `Declared width ${w}, measured ${real.width}`)
68
  if (h) check(Number(h) === real.height, `Declared height ${h}, measured ${real.height}`)
69
  console.log(`og:image measured ${real.width}×${real.height} (declared ${w ?? '—'}×${h ?? '—'})`)
70
}
71

72
//4. The JSON-LD must be parseable and have all fields present
73
const ld = html.match(
74
  /<script[^>]+application\/ld\+json[^>]*>([\s\S]*?)<\/script>/i,
75
)?.[1]
76
if (!ld) {
77
  fails.push('No JSON-LD in the page')
78
} else {
79
  try {
80
    const data = JSON.parse(ld)
81
    const nodes = data['@graph'] ?? [data]
82
    const post = nodes.find((n) => /Article|BlogPosting/.test(n['@type'] ?? ''))
83
    check(!!post, 'No Article/BlogPosting in the JSON-LD')
84
    for (const key of ['headline', 'datePublished', 'author', 'image']) {
85
      check(post && post[key], `JSON-LD missing ${key}`)
86
    }
87
  } catch (err) {
88
    fails.push(`JSON-LD is not valid JSON: ${err.message}`)
89
  }
90
}
91

92
if (fails.length) {
93
  for (const f of fails) console.error(`✗ ${f}`)
94
  process.exit(1)
95
}
96
console.log('✓ Open Graph and structured data checks passed')

Item 3 is the most valuable part of the entire script. It turns all the earlier “should be consistent in theory” assumptions into a real measurement—you don’t have to trust anyone’s memory (including your own) about image dimensions.

Summary#

• Social cards rely on og:* and twitter:*, search rich results rely on JSON-LD—you need both, and neither replaces the other;
• Open Graph has only four required properties; og:image must be an absolute URL, and og:image:width/height must match the image’s actual pixels;
• The property name for twitter:* is name; images that are too small get silently downgraded;
• Structured data has “no required properties,” but headline / image / datePublished / author effectively determines whether it’s valid;
• All failures are silent—so don’t rely on your eyes; use a script that can measure images itself to turn this into an observable check.

References#

• The Open Graph protocol (ogp.me)
• Google Search Central: Article (Article, NewsArticle, BlogPosting) structured data
• Google Search Central: Structured Data Markup Testing Tool
• Vercel Satori: Convert HTML and CSS to SVG
• Facebook Sharing Debugger