Typed Schema.org JSON-LD for React

Common errors

• Type '{ "@context": string; "@type": string; name: string; age: number; }' is not assignable to type 'Person'. Object literal may only specify known properties, and 'age' does not exist in type 'Person'.

  cause The JSON-LD object being passed to the `item` prop does not strictly conform to the `schema-dts` TypeScript definition for the specified Schema.org type (e.g., `Person` type does not have an 'age' property, or it expects a different type).
  fix Consult the `schema-dts` type definitions or the official Schema.org documentation to ensure all properties and their types within your JSON-LD object precisely match the expected schema. Use only valid properties for the given `@type`.

• ReferenceError: JsonLd is not defined

  cause This error typically indicates that the `JsonLd` component was not correctly imported or your JavaScript environment does not properly support ES module syntax, leading to `JsonLd` being `undefined` at runtime.
  fix Verify that `import { JsonLd } from 'react-schemaorg';` is correctly used at the top of your file. Ensure your build system (e.g., Webpack, Rollup, Babel) is configured to handle ES module imports for React components.

• Property 'script' does not exist on type 'IntrinsicAttributes & IntrinsicClassAttributes<Helmet> & Readonly<HelmetProps>'. Did you mean 'scriptElements'?

  cause When using `react-helmet` (or forks like `react-helmet-async`), the prop for passing script elements might vary between versions. Older versions might use `script`, while newer ones or `react-helmet-async` often use `scriptElements`.
  fix Check the documentation for your specific `react-helmet` library version. If `script` is not working, try passing the `helmetJsonLdProp` output to the `scriptElements` prop: `<Helmet scriptElements={[helmetJsonLdProp(...)]} />`.

Warnings

• breaking Version 2.0.0 increased the minimum required Node.js version to 12.0.0 and the minimum EcmaScript target to ES2019. Projects using older Node.js versions or build environments targeting older ES standards will encounter compatibility issues.
  Fix: Upgrade your Node.js environment to version 12.0.0 or higher. Ensure your project's build configuration (e.g., `tsconfig.json` `target`) is set to ES2019 or later.
• breaking A critical XSS vulnerability (Issue #9) was patched in v1.0.1. The fix involves HTML-escaping characters (`&`, `<`, `>`, `"`, `'`) within the JSON-LD payload to ensure compliance with the JSON-LD standard for script elements. While functionally a 'no-op', any downstream systems relying on unescaped characters in the JSON-LD within `<script>` tags might be affected.
  Fix: No code fix is generally required for `react-schemaorg` itself. However, ensure that any tools or services consuming the JSON-LD from your application are capable of correctly parsing HTML-escaped content within `<script type="application/ld+json">` tags.
• gotcha In v1.0.2, the library's build target was changed from ES2015 to ES5. This was done to improve compatibility with older build toolchains that may not correctly handle ES2015 'class' syntax. While generally a positive change for broader compatibility, projects with highly optimized build processes specifically tailored for ES2015 output might observe minor behavioral changes or require adjustments.
  Fix: Review your project's build pipeline (e.g., Babel, Webpack configurations) if you experience unexpected behavior or build output differences. Most projects should benefit from this change without explicit modification.

Install

• npm install react-schemaorg npm
• yarn add react-schemaorg yarn
• pnpm add react-schemaorg pnpm

Imports

• JsonLd
  wrong:

  const JsonLd = require('react-schemaorg').JsonLd;

  correct:

  import { JsonLd } from 'react-schemaorg';

  This is the primary React component for embedding JSON-LD directly into a React tree. Ensure named import for ESM setups.
• jsonLdScriptProps
  wrong:

  import jsonLdScriptProps from 'react-schemaorg/jsonLdScriptProps';

  correct:

  import { jsonLdScriptProps } from 'react-schemaorg';

  A utility function returning script tag properties, ideal for use with `next/head` or other scenarios requiring direct `<script>` tag creation. It's a named export.
• helmetJsonLdProp
  wrong:

  import { Helmet } from 'react-helmet'; const jsonLd = helmetJsonLdProp(...); // Incorrectly assuming it's part of react-helmet

  correct:

  import { helmetJsonLdProp } from 'react-schemaorg';

  This function generates a JSON-LD object specifically formatted for use within `react-helmet`'s `script` (or `scriptElements`) prop array.
• Person (type)
  wrong:

  import { Person } from 'schema-dts';

  correct:

  import type { Person } from 'schema-dts';

  While not from `react-schemaorg` directly, types from `schema-dts` are fundamental for type-safe usage. Use `import type` to avoid bundling unnecessary runtime code.

Quickstart

This quickstart demonstrates how to embed Schema.org JSON-LD data into a React component using the `<JsonLd>` component from `react-schemaorg`. It defines a `Person` schema for 'Grace Hopper' with various properties, showcasing type-safe data structuring for search engines and other semantic web consumers, leveraging TypeScript definitions from `schema-dts`.

import { Person } from "schema-dts";
import { JsonLd } from "react-schemaorg";
import React from 'react';

// Install peer dependencies:
// npm install schema-dts react-schemaorg react

/**
 * A React component demonstrating the embedding of structured data
 * for Grace Hopper using Schema.org's Person type.
 */
export function GraceHopperJsonLd() {
  return (
    <JsonLd<Person>
      item={{
        "@context": "https://schema.org",
        "@type": "Person",
        name: "Grace Hopper",
        alternateName: "Grace Brewster Murray Hopper",
        alumniOf: {
          "@type": "CollegeOrUniversity",
          name: ["Yale University", "Vassar College"],
        },
        knowsAbout: ["Compilers", "Computer Science", "COBOL", "Debugging"],
        url: "https://en.wikipedia.org/wiki/Grace_Hopper",
        sameAs: [
          "https://www.wikidata.org/wiki/Q11652",
          "https://viaf.org/viaf/100384877",
          "https://isni.org/isni/000000011856578X"
        ]
      }}
    />
  );
}

// Example of how to use the component within a larger React application
const App = () => (
  <div>
    <h1>Welcome to My Application</h1>
    <p>This page features an article about a notable figure.</p>
    {/* The JsonLd component will render a script tag in the document head */}
    <GraceHopperJsonLd />
    <footer>
      <p>Structured data is included for SEO purposes.</p>
    </footer>
  </div>
);

export default App;