{"id":11850,"library":"react-schemaorg","title":"Typed Schema.org JSON-LD for React","description":"react-schemaorg is a library designed to simplify the integration of structured data into React applications using Schema.org JSON-LD. It leverages the `schema-dts` package for robust TypeScript definitions, ensuring strong type safety when defining rich snippets, which helps prevent common errors in structured data implementation. The current stable version is 2.0.1, with releases typically addressing dependency updates, minor feature enhancements like `@graph` key support, or improved compatibility with popular head management libraries such as Next.js `next/head` and `react-helmet`. Key differentiators include its strong emphasis on type-checking through `schema-dts`, the provision of both a declarative `<JsonLd>` component and utility functions (`jsonLdScriptProps`, `helmetJsonLdProp`) for flexible integration, and its focus on secure JSON-LD parsing to mitigate potential XSS vulnerabilities.","status":"active","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/google/react-schemaorg","tags":["javascript","react","jsonld","JSON-LD","typescript","schema.org","Semantic Web","semantic-web","Linked Data"],"install":[{"cmd":"npm install react-schemaorg","lang":"bash","label":"npm"},{"cmd":"yarn add react-schemaorg","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-schemaorg","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core React library required for component rendering.","package":"react","optional":false},{"reason":"Provides TypeScript definitions for Schema.org types, enabling type-safe JSON-LD creation.","package":"schema-dts","optional":false},{"reason":"Required for type checking and compilation of the library itself and for type-safe usage in projects.","package":"typescript","optional":false}],"imports":[{"note":"This is the primary React component for embedding JSON-LD directly into a React tree. Ensure named import for ESM setups.","wrong":"const JsonLd = require('react-schemaorg').JsonLd;","symbol":"JsonLd","correct":"import { JsonLd } from 'react-schemaorg';"},{"note":"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.","wrong":"import jsonLdScriptProps from 'react-schemaorg/jsonLdScriptProps';","symbol":"jsonLdScriptProps","correct":"import { jsonLdScriptProps } from 'react-schemaorg';"},{"note":"This function generates a JSON-LD object specifically formatted for use within `react-helmet`'s `script` (or `scriptElements`) prop array.","wrong":"import { Helmet } from 'react-helmet'; const jsonLd = helmetJsonLdProp(...); // Incorrectly assuming it's part of react-helmet","symbol":"helmetJsonLdProp","correct":"import { helmetJsonLdProp } from 'react-schemaorg';"},{"note":"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.","wrong":"import { Person } from 'schema-dts';","symbol":"Person (type)","correct":"import type { Person } from 'schema-dts';"}],"quickstart":{"code":"import { Person } from \"schema-dts\";\nimport { JsonLd } from \"react-schemaorg\";\nimport React from 'react';\n\n// Install peer dependencies:\n// npm install schema-dts react-schemaorg react\n\n/**\n * A React component demonstrating the embedding of structured data\n * for Grace Hopper using Schema.org's Person type.\n */\nexport function GraceHopperJsonLd() {\n  return (\n    <JsonLd<Person>\n      item={{\n        \"@context\": \"https://schema.org\",\n        \"@type\": \"Person\",\n        name: \"Grace Hopper\",\n        alternateName: \"Grace Brewster Murray Hopper\",\n        alumniOf: {\n          \"@type\": \"CollegeOrUniversity\",\n          name: [\"Yale University\", \"Vassar College\"],\n        },\n        knowsAbout: [\"Compilers\", \"Computer Science\", \"COBOL\", \"Debugging\"],\n        url: \"https://en.wikipedia.org/wiki/Grace_Hopper\",\n        sameAs: [\n          \"https://www.wikidata.org/wiki/Q11652\",\n          \"https://viaf.org/viaf/100384877\",\n          \"https://isni.org/isni/000000011856578X\"\n        ]\n      }}\n    />\n  );\n}\n\n// Example of how to use the component within a larger React application\nconst App = () => (\n  <div>\n    <h1>Welcome to My Application</h1>\n    <p>This page features an article about a notable figure.</p>\n    {/* The JsonLd component will render a script tag in the document head */}\n    <GraceHopperJsonLd />\n    <footer>\n      <p>Structured data is included for SEO purposes.</p>\n    </footer>\n  </div>\n);\n\nexport default App;\n","lang":"typescript","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","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).","error":"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'."},{"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.","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.","error":"ReferenceError: JsonLd is not defined"},{"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(...)]} />`.","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`.","error":"Property 'script' does not exist on type 'IntrinsicAttributes & IntrinsicClassAttributes<Helmet> & Readonly<HelmetProps>'. Did you mean 'scriptElements'?"}],"ecosystem":"npm"}