JSON-LD

Core Idea

Adiciona dados estruturados (JSON-LD) às páginas para search engines e IA entenderem o conteúdo além do texto puro, renderizando um <script type="application/ld+json"> diretamente em layout.js/page.js.

Key Concepts

• JSON-LD: formato de dados estruturados (schema.org) que descreve entidades como produto, pessoa, evento, receita etc.
• Sanitização obrigatória: JSON.stringify não escapa strings maliciosas; é preciso substituir < por < (ou usar serialize-javascript) para evitar XSS.
• <script> nativo vs next/script: use <script> nativo para JSON-LD porque next/script é otimizado para JS executável, não para dados estruturados.
• schema-dts: pacote comunitário para tipar o objeto JSON-LD com TypeScript.

Code Examples

// app/products/[id]/page.tsx
export default async function Page({ params }) {
  const { id } = await params
  const product = await getProduct(id)

  const jsonLd = {
    '@context': 'https://schema.org',
    '@type': 'Product',
    name: product.name,
    image: product.image,
    description: product.description,
  }

  return (
    <section>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{
          __html: JSON.stringify(jsonLd).replace(/</g, '\\u003c'),
        }}
      />
      {/* ... */}
    </section>
  )
}

• O que demonstra: renderização segura de JSON-LD escapando < para prevenir XSS via dangerouslySetInnerHTML.

import { Product, WithContext } from 'schema-dts'

const jsonLd: WithContext<Product> = {
  '@context': 'https://schema.org',
  '@type': 'Product',
  name: 'Next.js Sticker',
  image: 'https://nextjs.org/imgs/sticker.png',
  description: 'Dynamic at the speed of static.',
}

• O que demonstra: tipagem forte de JSON-LD com schema-dts.

Anti-patterns

• JSON.stringify sem sanitização: expõe a aplicação a XSS injection se dados do usuário entrarem no JSON-LD.
• Usar next/script para JSON-LD: componente errado, pois é otimizado para execução de JS, não dados estruturados.

Key Takeaways

1. Renderize JSON-LD com <script type="application/ld+json"> nativo em layout.js/page.js.
2. Sempre escape < (<) no output do JSON.stringify, ou use serialize-javascript.
3. Valide o resultado com o Rich Results Test do Google ou o Schema Markup Validator.
4. Use schema-dts para tipagem TypeScript de entidades schema.org.

Connects To

• next/script: componente correto para scripts executáveis, contraste com este caso de uso.
• Metadata API: outra fonte de dados para SEO, complementar ao JSON-LD.