### Install project dependencies

Source: https://github.com/google/schema-dts/blob/main/README.md

Install all necessary dependencies for the project using npm.

```sh
npm install
```

--------------------------------

### Install schema-dts-gen

Source: https://github.com/google/schema-dts/blob/main/README.md

Install the schema-dts-gen package as a development dependency using npm.

```sh
npm install --save-dev schema-dts-gen
```

--------------------------------

### Install and Run schema-dts-gen

Source: https://github.com/google/schema-dts/blob/main/packages/schema-dts-gen/README.md

Installs the schema-dts-gen package as a development dependency and then runs it to generate typings from a specified ontology URL.

```sh
npm install --save-dev schema-dts-gen
npx schema-dts-gen --ontology=https://schema.org/version/latest/schemaorg-all-https.nt
```

--------------------------------

### Install schema-dts Package

Source: https://github.com/google/schema-dts/blob/main/README.md

Install the schema-dts NPM package as a development dependency.

```sh
npm install --save-dev schema-dts
```

--------------------------------

### React Product Schema Integration

Source: https://context7.com/google/schema-dts/llms.txt

Uses the `react-schemaorg` library to embed Product schema in a React component. Ensure `react-schemaorg` is installed.

```tsx
import {JsonLd} from 'react-schemaorg';
import type {Product} from 'schema-dts';

export function ProductPage() {
  return (
    <JsonLd<Product>
      item={{
        '@context': 'https://schema.org',
        '@type': 'Product',
        name: 'Classic Leather Wallet',
        offers: {'@type': 'Offer', price: 89, priceCurrency: 'USD'},
      }}
    />
  );
}
```

--------------------------------

### React: Inject JSON-LD with react-schemaorg

Source: https://github.com/google/schema-dts/blob/main/examples.md

Use the `<JsonLd>` component from `react-schemaorg` for XSS-safe JSON-LD serialization in React applications. Ensure `react-schemaorg` is installed.

```tsx
import {JsonLd} from 'react-schemaorg';
import type {Product} from 'schema-dts';

export function ProductPage() {
  return (
    <JsonLd<Product>
      item={{
        '@context': 'https://schema.org',
        '@type': 'Product',
        name: 'Classic Leather Wallet',
        offers: {
          '@type': 'Offer',
          price: 89,
          priceCurrency: 'USD',
        },
      }}
    />
  );
}
```

--------------------------------

### Define Simple Person Properties with schema-dts

Source: https://github.com/google/schema-dts/blob/main/packages/schema-dts/README.md

Example of defining a 'Person' object with various properties like name, birthDate, and awards using schema-dts types.

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

const inventor: Person = {
  '@type': 'Person',
  name: 'Grace Hopper',
  disambiguatingDescription: 'American computer scientist',
  birthDate: '1906-12-09',
  deathDate: '1992-01-01',
  awards: [
    'Presidential Medal of Freedom',
    'National Medal of Technology and Innovation',
    'IEEE Emanuel R. Piore Award',
  ],
};
```

--------------------------------

### Define WebSite Schema

Source: https://github.com/google/schema-dts/blob/main/README.md

Create a basic `WebSite` schema with name and URL. Use `WithContext` to include the JSON-LD context.

```typescript
import type {WebSite, WithContext} from 'schema-dts';

const site: WithContext<WebSite> = {
  '@context': 'https://schema.org',
  '@type': 'WebSite',
  name: 'Acme Corp',
  url: 'https://acme.com',
};
```

--------------------------------

### Define Product Schema with Offer

Source: https://github.com/google/schema-dts/blob/main/README.md

Structure a `Product` schema including details like name, description, image, SKU, brand, and offer information. Use `WithContext` for the JSON-LD context.

```typescript
import type {Product, WithContext} from 'schema-dts';

const product: WithContext<Product> = {
  '@context': 'https://schema.org',
  '@type': 'Product',
  name: 'Classic Leather Wallet',
  description: 'Full-grain leather bifold wallet with RFID blocking.',
  image: 'https://shop.example/images/wallet.jpg',
  sku: 'WALLET-001',
  brand: {
    '@type': 'Brand',
    name: 'Example Shop',
  },
  offers: {
    '@type': 'Offer',
    price: 89,
    priceCurrency: 'USD',
    availability: 'https://schema.org/InStock',
    url: 'https://shop.example/products/classic-wallet',
  },
};
```

--------------------------------

### Generate typings from a local .nt file

Source: https://context7.com/google/schema-dts/llms.txt

Generate typings from a local NTriples ontology file using the --file flag.

```sh
# Use a local .nt file
npx schema-dts-gen \
  --file=./my-ontology.nt \
  > custom-schema.d.ts
```

--------------------------------

### Generate typings from latest Schema.org core ontology

Source: https://context7.com/google/schema-dts/llms.txt

Generate typings from the latest Schema.org core ontology and pipe the output to a file. This command uses the default context.

```sh
# Generate typings from the latest Schema.org core ontology (writes to stdout)
npx schema-dts-gen \
  --ontology=https://schema.org/version/latest/schemaorg-all-https.nt \
  > schema.d.ts
```

--------------------------------

### Generate typings with multi-namespace context

Source: https://context7.com/google/schema-dts/llms.txt

Generate typings using a multi-namespace context, specifying prefixes for RDF schema and Schema.org.

```sh
# Multi-namespace context (rdf + schema prefixes)
npx schema-dts-gen \
  --ontology=https://schema.org/version/latest/schemaorg-all-https.nt \
  --context=rdf:http://www.w3.org/2000/01/rdf-schema,schema:https://schema.org \
  > schema-prefixed.d.ts
```

--------------------------------

### Define FAQPage Schema

Source: https://github.com/google/schema-dts/blob/main/README.md

Create an `FAQPage` schema with a list of questions and their accepted answers. Use `WithContext` for the JSON-LD context.

```typescript
import type {FAQPage, WithContext} from 'schema-dts';

const faq: WithContext<FAQPage> = {
  '@context': 'https://schema.org',
  '@type': 'FAQPage',
  mainEntity: [
    {
      '@type': 'Question',
      name: 'Do you ship internationally?',
      acceptedAnswer: {
        '@type': 'Answer',
        text: 'Yes, we ship to over 50 countries.',
      },
    },
    {
      '@type': 'Question',
      name: 'What is your return policy?',
      acceptedAnswer: {
        '@type': 'Answer',
        text: 'We offer a 30-day return policy on all items.',
      },
    },
  ],
};
```

--------------------------------

### Build Schema Typings Generator and Schema

Source: https://github.com/google/schema-dts/blob/main/README.md

Execute npm scripts to first build the generator and then generate the Schema.org typings. This is a common workflow for developers contributing to the project.

```sh
npm run build-gen && npm run build-schema
```

--------------------------------

### Generate TypeScript typings from Schema.org

Source: https://github.com/google/schema-dts/blob/main/README.md

Use npx to run the schema-dts-gen command, specifying the ontology URL to generate TypeScript typings. Ensure the ontology is compatible with Schema.org.

```sh
npx schema-dts-gen --ontology=https://schema.org/version/latest/schemaorg-all-https.nt
```

--------------------------------

### Load ontology quads from a remote URL

Source: https://context7.com/google/schema-dts/llms.txt

Use the loadTriples function to fetch an NTriples file from an HTTPS URL and parse it into an N3 Store. This function handles HTTP redirects automatically.

```ts
import {loadTriples} from 'schema-dts-gen';
// For local files, import from the internal path or use the CLI --file flag.
// The programmatic equivalent:
import {loadFile} from 'schema-dts-gen/dist/src/triples/reader.js';

// Remote — handles HTTP redirects automatically
const remoteStore = await loadTriples(
  'https://schema.org/version/latest/schemaorg-all-https.nt'
);
console.log(`Loaded ${remoteStore.size} quads`);

// Local file
const localStore = await loadFile('./ontologies/my-schema.nt');
console.log(`Loaded ${localStore.size} quads from local file`);
```

--------------------------------

### Define Organization Schema

Source: https://github.com/google/schema-dts/blob/main/README.md

Create a basic `Organization` schema with essential properties like name, URL, logo, and social media links. Use `WithContext` to include the JSON-LD context.

```typescript
import type {Organization, WithContext} from 'schema-dts';

const org: WithContext<Organization> = {
  '@context': 'https://schema.org',
  '@type': 'Organization',
  name: 'Acme Corp',
  url: 'https://acme.com',
  logo: 'https://acme.com/logo.png',
  sameAs: ['https://twitter.com/acme', 'https://www.linkedin.com/company/acme'],
};
```

--------------------------------

### Define WebSite with SearchAction

Source: https://github.com/google/schema-dts/blob/main/README.md

Embed a `SearchAction` within a `WebSite` schema, using `WithActionConstraints` to define its input.

```typescript
import type {SearchAction, WebSite, WithActionConstraints} from 'schema-dts';

const website: WebSite = {
  '@type': 'WebSite',
  potentialAction: {
    '@type': 'SearchAction',
    'query-input': 'required name=search_term_string',
  } as WithActionConstraints<SearchAction>,
};
```

--------------------------------

### Build Schema Typings Generator only

Source: https://github.com/google/schema-dts/blob/main/README.md

Run the npm script specifically to build the schema-dts generator without generating the Schema.org typings. Useful for development of the generator itself.

```sh
npm run build-gen
```

--------------------------------

### Define Article Schema

Source: https://github.com/google/schema-dts/blob/main/README.md

Structure an `Article` schema with headline, publication dates, author, image, and description. Use `WithContext` for the JSON-LD context.

```typescript
import type {Article, WithContext} from 'schema-dts';

const article: WithContext<Article> = {
  '@context': 'https://schema.org',
  '@type': 'Article',
  headline: 'How to choose a leather wallet',
  datePublished: '2026-03-01',
  dateModified: '2026-03-15',
  author: {
    '@type': 'Person',
    name: 'Jane Smith',
    url: 'https://blog.example/authors/jane',
  },
  image: 'https://blog.example/images/wallet-guide.jpg',
  description: 'A practical guide to choosing a leather wallet that lasts.',
};
```

--------------------------------

### Generate typings from a specific Schema.org version

Source: https://context7.com/google/schema-dts/llms.txt

Generate typings from a specific version of the Schema.org ontology by providing the version number in the ontology URL.

```sh
# Use a specific Schema.org version
npx schema-dts-gen \
  --ontology=https://schema.org/version/26.0/schemaorg-all-https.nt \
  > schema-26.d.ts
```

--------------------------------

### Generate typings with verbose output

Source: https://context7.com/google/schema-dts/llms.txt

Generate typings with verbose output enabled, directing diagnostic logs to stderr and declarations to stdout.

```sh
# Verbose output (diagnostic logs on stderr, declarations on stdout)
npx schema-dts-gen \
  --ontology=https://schema.org/version/latest/schemaorg-all-https.nt \
  --verbose \
  > schema.d.ts
```

--------------------------------

### Svelte: Inject JSON-LD into <svelte:head>

Source: https://github.com/google/schema-dts/blob/main/examples.md

Use Svelte's `<svelte:head>` to inject JSON-LD into the document's head. The provided `safeJsonLd` function ensures XSS safety by escaping special characters. Import necessary types from `schema-dts`.

```svelte
<script lang="ts">
  import type {Organization, WithContext} from 'schema-dts';

  const org: WithContext<Organization> = {
    '@context': 'https://schema.org',
    '@type': 'Organization',
    name: 'Acme Corp',
    url: 'https://acme.com',
    logo: 'https://acme.com/logo.png',
  };

  function safeJsonLd(data: object): string {
    return JSON.stringify(data)
      .replace(/</g, '\u003C')
      .replace(/>/g, '\u003E')
      .replace(/&/g, '\u0026')
      .replace(/'/g, '\u0027');
  }
</script>

<svelte:head>
  {@html `<script type="application/ld+json">${safeJsonLd(org)}</script>`}
</svelte:head>
```

--------------------------------

### Merge Multiple Schema Types with MergeLeafTypes

Source: https://github.com/google/schema-dts/blob/main/packages/schema-dts/README.md

Shows how to combine multiple concrete schema types, such as 'Product' and 'SoftwareApplication', into a single type using `MergeLeafTypes` for objects that represent more than one schema type.

```typescript
import type {
  MergeLeafTypes,
  ProductLeaf,
  SoftwareApplicationLeaf,
  WithContext,
} from 'schema-dts';

const app: WithContext<MergeLeafTypes<[ProductLeaf, SoftwareApplicationLeaf]>> =
  {
    '@context': 'https://schema.org',
    '@type': ['Product', 'SoftwareApplication'],
    name: 'My App',
    offers: {
      '@type': 'Offer',
      price: 89,
      priceCurrency: 'USD',
    },
    operatingSystem: 'Any',
  };
```

--------------------------------

### Annotate SearchAction with Input Constraints

Source: https://github.com/google/schema-dts/blob/main/README.md

Use `WithActionConstraints` to add input and output constraints to action types like `SearchAction`. The `query-input` property specifies the required input name.

```typescript
import type {SearchAction, WithActionConstraints} from 'schema-dts';

const potentialAction: WithActionConstraints<SearchAction> = {
  '@type': 'SearchAction',
  'query-input': 'required name=search_term_string',
  // ...
};
```

--------------------------------

### Astro: Inject JSON-LD with inline script tag

Source: https://github.com/google/schema-dts/blob/main/examples.md

Render JSON-LD directly within an Astro component's template using an inline `<script>` tag. The `safeJsonLd` helper function is used for XSS safety. Ensure `schema-dts` types are imported.

```astro
---
import type {FAQPage, WithContext} from 'schema-dts';

const faq: WithContext<FAQPage> = {
  '@context': 'https://schema.org',
  '@type': 'FAQPage',
  mainEntity: [
    {
      '@type': 'Question',
      name: 'Do you ship internationally?',
      acceptedAnswer: {
        '@type': 'Answer',
        text: 'Yes, we ship to over 50 countries.',
      },
    },
  ],
};

function safeJsonLd(data: object): string {
  return JSON.stringify(data)
    .replace(/</g, '\u003C')
    .replace(/>/g, '\u003E')
    .replace(/&/g, '\u0026')
    .replace(/'/g, '\u0027');
}
---

<script type="application/ld+json" set:html={safeJsonLd(faq)} />
```

--------------------------------

### Parse context specification for schema-dts-gen

Source: https://context7.com/google/schema-dts/llms.txt

Use the Context.Parse static factory to convert CLI --context flag values into a Context object. It accepts a single URL or a comma-separated list of name:url pairs.

```ts
import {Context} from 'schema-dts-gen/dist/src/ts/context.js';

// Single URL context (default)
const singleCtx = Context.Parse('https://schema.org');

// Multi-namespace context
const multiCtx = Context.Parse(
  'rdf:http://www.w3.org/2000/01/rdf-schema,' +
  'schema:https://schema.org'
);

// Resolve a property name within the context
import {NamedNode} from 'n3';
const node = new NamedNode('https://schema.org/name');
console.log(singleCtx.getScopedName(node)); // 'name'
console.log(multiCtx.getScopedName(node));  // 'schema:name'

// Validation errors
try {
  Context.Parse(''); // throws: Invalid empty context
} catch (e) {
  console.error(e);
}
```

--------------------------------

### Use JSON-LD Context with schema-dts

Source: https://github.com/google/schema-dts/blob/main/packages/schema-dts/README.md

Demonstrates how to use the `WithContext<T>` type to include the required '@context' property for JSON-LD, along with a helper function to stringify the JSON-LD object.

```typescript
import type {Organization, Thing, WithContext} from 'schema-dts';

export function JsonLd<T extends Thing>(json: WithContext<T>): string {
  return `<script type="application/ld+json">
${JSON.stringify(json)}
</script>`;
}

export const MY_ORG = JsonLd<Organization>({
  '@context': 'https://schema.org',
  '@type': 'Corporation',
  name: 'Google LLC',
});
```

--------------------------------

### Vanilla TypeScript: Framework-agnostic JSON-LD injection

Source: https://github.com/google/schema-dts/blob/main/examples.md

Inject JSON-LD directly into the document's head using vanilla TypeScript without relying on any framework. This method involves creating a script element and appending it to the document head. Ensure `schema-dts` types are imported.

```ts
import type {WebSite, WithContext} from 'schema-dts';

const site: WithContext<WebSite> = {
  '@context': 'https://schema.org',
  '@type': 'WebSite',
  name: 'Acme Corp',
  url: 'https://acme.com',
};

const script = document.createElement('script');
script.type = 'application/ld+json';
script.textContent = JSON.stringify(site);
document.head.appendChild(script);
```

--------------------------------

### Next.js: Inject JSON-LD with Script component

Source: https://github.com/google/schema-dts/blob/main/examples.md

Utilize Next.js's built-in `<Script>` component to inject JSON-LD. A helper function `safeJsonLd` is provided to escape characters that could break out of a `<script>` tag, ensuring XSS safety. Import `Script` from 'next/script'.

```tsx
import Script from 'next/script';
import type {Article, WithContext} from 'schema-dts';

function safeJsonLd(data: WithContext<Article>): string {
  return JSON.stringify(data)
    .replace(/</g, '\u003C')
    .replace(/>/g, '\u003E')
    .replace(/&/g, '\u0026')
    .replace(/'/g, '\u0027');
}

export default function BlogPost() {
  const article: WithContext<Article> = {
    '@context': 'https://schema.org',
    '@type': 'Article',
    headline: 'How to choose a leather wallet',
    datePublished: '2025-03-01',
    author: {'@type': 'Person', name: 'Jane Smith'},
  };

  return (
    <>
      <Script
        id="article-jsonld"
        type="application/ld+json"
        dangerouslySetInnerHTML={{__html: safeJsonLd(article)}}
      />
      <article>{/* page content */}</article>
    </>
  );
}
```

--------------------------------

### Generate typings excluding deprecated types

Source: https://context7.com/google/schema-dts/llms.txt

Generate typings while excluding deprecated types and properties by using the --nodeprecated flag.

```sh
# Exclude deprecated types and properties
npx schema-dts-gen \
  --ontology=https://schema.org/version/latest/schemaorg-all-https.nt \
  --nodeprecated \
  > schema-nodeprecated.d.ts
```

--------------------------------

### Programmatic generation of TypeScript declarations

Source: https://context7.com/google/schema-dts/llms.txt

Use the WriteDeclarations function to programmatically generate TypeScript typings from an ontology URL. This function requires an N3 Store, a flag for deprecated inclusion, a Context instance, and a write callback.

```ts
import {WriteDeclarations, loadTriples} from 'schema-dts-gen';
import {Context} from 'schema-dts-gen'; // re-exported from ts/context.js
import {createWriteStream} from 'fs';

async function generateTypings(ontologyUrl: string, outPath: string) {
  // 1. Load the ontology into an N3 Store
  const store = await loadTriples(ontologyUrl);

  // 2. Parse the context specification
  const context = Context.Parse('https://schema.org');

  // 3. Open a write stream
  const out = createWriteStream(outPath, {encoding: 'utf-8'});
  const writes: Promise<void>[] = [];

  // 4. Stream TypeScript declarations
  await WriteDeclarations(
    store,
    /*includeDeprecated=*/ true,
    context,
    (chunk: string) => {
      writes.push(new Promise((res, rej) =>
        out.write(chunk, err => (err ? rej(err) : res()))
      ));
    },
  );

  await Promise.all(writes);
  out.end();
  console.log(`Typings written to ${outPath}`);
}

generateTypings(
  'https://schema.org/version/latest/schemaorg-all-https.nt',
  './dist/schema.d.ts',
).catch(console.error);
```

--------------------------------

### Vanilla TypeScript DOM Injection for WebSite Schema

Source: https://context7.com/google/schema-dts/llms.txt

Injects WebSite schema directly into the DOM using vanilla TypeScript. This method manually creates a script element and appends it to the document's head.

```ts
import type {WebSite, WithContext} from 'schema-dts';

const site: WithContext<WebSite> = {
  '@context': 'https://schema.org',
  '@type': 'WebSite',
  name: 'Acme Corp',
  url: 'https://acme.com',
};
const script = document.createElement('script');
script.type = 'application/ld+json';
script.textContent = JSON.stringify(site);
document.head.appendChild(script);
```

--------------------------------

### Thing - Root Union Type for Schema.org Classes

Source: https://context7.com/google/schema-dts/llms.txt

Thing is the top-level discriminated union for all Schema.org classes. Specifying a narrow '@type' activates its sub-interface, while a broad '@type' restricts properties to those defined on Thing itself. '@type' is required.

```typescript
import type {Thing} from 'schema-dts';

// @ts-expect-error '@type' is required
const missing: Thing = {};

// Valid: any known Schema.org type string
const thing: Thing = {'@type': 'Thing'};
const person: Thing = {'@type': 'Person', name: 'Ada'};
const product: Thing = {
  '@type': 'Product',
  name: 'Classic Leather Wallet',
  sku: 'WALLET-001',
  brand: {'@type': 'Brand', name: 'Example Shop'},
  offers: {
    '@type': 'Offer',
    price: 89,
    priceCurrency: 'USD',
    availability: 'https://schema.org/InStock',
  },
};

// Excess property checking: sub-properties disallowed when @type is 'Thing'
const tooWide: Thing = {
  '@type': 'Thing',
  name: 'ok',
  // @ts-expect-error 'additionalName' is not on Thing
  additionalName: ['alias'],
};

```

--------------------------------

### WithActionConstraints<T> - Annotate Action Properties

Source: https://context7.com/google/schema-dts/llms.txt

WithActionConstraints widens an Action type to accept '{property}-input' and '{property}-output' suffixed keys. Cast to this type at the point of use to enable these additional keys, which are not present on plain Action types.

```typescript
import type {SearchAction, WebSite, WithActionConstraints} from 'schema-dts';

// Stand-alone annotated action
const action: WithActionConstraints<SearchAction> = {
  '@type': 'SearchAction',
  'query-input': 'required name=search_term_string',
};

// Nested within a WebSite — cast at point of use
const website: WebSite = {
  '@type': 'WebSite',
  name: 'Acme Search',
  url: 'https://acme.com',
  potentialAction: {
    '@type': 'SearchAction',
    target: {
      '@type': 'EntryPoint',
      urlTemplate: 'https://acme.com/search?q={search_term_string}',
    },
    'query-input': 'required name=search_term_string',
  } as WithActionConstraints<SearchAction>,
};

// Type error: '-input' suffix is only valid on WithActionConstraints, not plain action
const bad: SearchAction = {
  '@type': 'SearchAction',
  // @ts-expect-error 'query-input' not on plain SearchAction
  'query-input': 'required name=search_term_string',
};

```

--------------------------------

### Use Root Context with schema-dts

Source: https://github.com/google/schema-dts/blob/main/README.md

Augment a Person type with WithContext to include the '@context' property for Schema.org.

```ts
import type {Person, WithContext} from 'schema-dts';

const p: WithContext<Person> = {
  '@context': 'https://schema.org',
  '@type': 'Person',
  name: 'Eve',
  affiliation: {
    '@type': 'School',
    name: 'Nice School',
  },
};
```

--------------------------------

### Next.js Article Schema with Safe Serialization

Source: https://context7.com/google/schema-dts/llms.txt

Embeds Article schema in a Next.js application using the `Script` component. Includes a `safeJsonLd` helper to prevent XSS vulnerabilities by escaping special characters.

```tsx
import Script from 'next/script';
import type {Article, WithContext} from 'schema-dts';

function safeJsonLd(data: object): string {
  return JSON.stringify(data)
    .replace(/</g, '\u003C').replace(/>/g, '\u003E')
    .replace(/&/g, '\u0026').replace(/'/g, '\u0027');
}

export default function BlogPost() {
  const article: WithContext<Article> = {
    '@context': 'https://schema.org',
    '@type': 'Article',
    headline: 'How to choose a leather wallet',
    datePublished: '2025-03-01',
    author: {'@type': 'Person', name: 'Jane Smith'},
  };
  return (
    <>
      <Script
        id="article-jsonld"
        type="application/ld+json"
        dangerouslySetInnerHTML={{__html: safeJsonLd(article)}}
      />
      <article>{/* page content */}</article>
    </>
  );
}
```

--------------------------------

### WithContext<T>

Source: https://context7.com/google/schema-dts/llms.txt

The WithContext<T> type adds a required '@context' property to any Schema.org type T. This is essential for valid JSON-LD snippets embedded in HTML.

```APIDOC
## WithContext<T> — Add `@context` to a top-level JSON-LD node

`WithContext<T>` is an intersection type that extends any Schema.org type `T` with a required `"@context"` property whose value is constrained to the exact URL used when generating the typings (default `"https://schema.org"`). Use it on the outermost object of every JSON-LD snippet you embed in a `<script type="application/ld+json">` tag.

### Example Usage

```ts
import type {Organization, Person, WithContext} from 'schema-dts';

// Person with context
const person: WithContext<Person> = {
  '@context': 'https://schema.org',
  '@type': 'Person',
  name: 'Grace Hopper',
  birthDate: '1906-12-09',
  awards: [
    'Presidential Medal of Freedom',
    'National Medal of Technology and Innovation',
  ],
};

// Organization with context — '@context' must be exactly 'https://schema.org'
const org: WithContext<Organization> = {
  '@context': 'https://schema.org',
  '@type': 'Organization',
  name: 'Acme Corp',
  url: 'https://acme.com',
  logo: 'https://acme.com/logo.png',
  sameAs: ['https://twitter.com/acme', 'https://linkedin.com/company/acme'],
};

// Type error: wrong context URL
// @ts-expect-error
const bad: WithContext<Person> = {'@context': 'https://google.com', '@type': 'Person'};

// Helper to serialize safely for injection into HTML
function safeJsonLd(data: WithContext<import('schema-dts').Thing>): string {
  return JSON.stringify(data)
    .replace(/</g, '\u003C')
    .replace(/>/g, '\u003E')
    .replace(/&/g, '\u0026')
    .replace(/'/g, '\u0027');
}
// <script type="application/ld+json">${safeJsonLd(person)}</script>
```
```

--------------------------------

### Graph

Source: https://context7.com/google/schema-dts/llms.txt

The Graph type provides a typed interface for JSON-LD documents containing multiple, interconnected top-level nodes under a "@graph" key. Each element in the array can be any Schema.org type.

```APIDOC
## Graph — JSON-LD `@graph` with interconnected nodes

`Graph` is a typed interface for JSON-LD documents that contain multiple, interlinked top-level nodes under a `"@graph"` key. Each array element is a `Thing` (the top-level union of all Schema.org types) and any node can carry an `"@id"` IRI. Other nodes can reference it with an ID stub `{ '@id': '...' }` (typed as `IdReference`).

### Example Usage

```ts
import type {Graph} from 'schema-dts';

const graph: Graph = {
  '@context': 'https://schema.org',
  '@graph': [
    {
      '@type': 'Person',
      '@id': 'https://my.site/#alyssa',
      name: 'Alyssa P. Hacker',
      hasOccupation: {
        '@type': 'Occupation',
        name: 'LISP Hacker',
        qualifications: 'Knows LISP',
      },
      mainEntityOfPage: {'@id': 'https://my.site/about/#page'},
      subjectOf: {'@id': 'https://my.site/about/#page'},
    },
    {
      '@type': 'WebPage',
      '@id': 'https://my.site/about/#page',
      url: 'https://my.site/about/',
      name: "About | Alyssa P. Hacker's Website",
      inLanguage: 'en-US',
      about: {'@id': 'https://my.site/#alyssa'},
      mainEntity: {'@id': 'https://my.site/#alyssa'},
    },
    {
      '@type': 'WebSite',
      '@id': 'https://my.site/#site',
      url: 'https://my.site',
      name: "Alyssa P. Hacker's Website",
      inLanguage: 'en-US',
      mainEntity: {'@id': 'https://my.site/#alyssa'},
    },
  ],
};

// Type-checked: unknown property is caught at compile time
const badGraph: Graph = {
  '@context': 'https://schema.org',
  '@graph': [
    {
      '@type': 'Thing',
      // @ts-expect-error Unknown property
      unknownProp: 5,
    },
  ],
};
```
```

--------------------------------

### Structure Interconnected Data with schema-dts Graph

Source: https://github.com/google/schema-dts/blob/main/packages/schema-dts/README.md

Illustrates how to define interconnected JSON-LD nodes using the `Graph` type, including assigning unique `@id`s to nodes and referencing them from other parts of the graph. This is useful for representing complex relationships between entities.

```typescript
import type {Graph} from 'schema-dts';

const graph: Graph = {
  '@context': 'https://schema.org',
  '@graph': [
    {
      '@type': 'Person',
      '@id': 'https://my.site/#alyssa',
      name: 'Alyssa P. Hacker',
      hasOccupation: {
        '@type': 'Occupation',
        name: 'LISP Hacker',
        qualifications: 'Knows LISP',
      },
      mainEntityOfPage: {'@id': 'https://my.site/about/#page'},
      subjectOf: {'@id': 'https://my.site/about/#page'},
    },
    {
      '@type': 'AboutPage',
      '@id': 'https://my.site/#site',
      url: 'https://my.site',
      name: "Alyssa P. Hacker's Website",
      inLanguage: 'en-US',
      description: 'The personal website of LISP legend Alyssa P. Hacker',
      mainEntity: {'@id': 'https://my.site/#alyssa'},
    },
    {
      '@type': 'WebPage',
      '@id': 'https://my.site/about/#page',
      url: 'https://my.site/about/',
      name: "About | Alyssa P. Hacker's Website",
      inLanguage: 'en-US',
      isPartOf: {
        '@id': 'https://my.site/#site',
      },
      about: {'@id': 'https://my.site/#alyssa'},
      mainEntity: {'@id': 'https://my.site/#alyssa'},
    },
  ],
};
```

--------------------------------

### Handle JSON-LD @graph with Interconnected Nodes

Source: https://context7.com/google/schema-dts/llms.txt

The Graph type provides a typed interface for JSON-LD documents with multiple top-level nodes under a '@graph' key. Each node can have an '@id' and be referenced by other nodes using an '@id' stub.

```typescript
import type {Graph} from 'schema-dts';

const graph: Graph = {
  '@context': 'https://schema.org',
  '@graph': [
    {
      '@type': 'Person',
      '@id': 'https://my.site/#alyssa',
      name: 'Alyssa P. Hacker',
      hasOccupation: {
        '@type': 'Occupation',
        name: 'LISP Hacker',
        qualifications: 'Knows LISP',
      },
      mainEntityOfPage: {'@id': 'https://my.site/about/#page'},
      subjectOf: {'@id': 'https://my.site/about/#page'},
    },
    {
      '@type': 'WebPage',
      '@id': 'https://my.site/about/#page',
      url: 'https://my.site/about/',
      name: "About | Alyssa P. Hacker's Website",
      inLanguage: 'en-US',
      about: {'@id': 'https://my.site/#alyssa'},
      mainEntity: {'@id': 'https://my.site/#alyssa'},
    },
    {
      '@type': 'WebSite',
      '@id': 'https://my.site/#site',
      url: 'https://my.site',
      name: "Alyssa P. Hacker's Website",
      inLanguage: 'en-US',
      mainEntity: {'@id': 'https://my.site/#alyssa'},
    },
  ],
};

// Type-checked: unknown property is caught at compile time
const badGraph: Graph = {
  '@context': 'https://schema.org',
  '@graph': [
    {
      '@type': 'Thing',
      // @ts-expect-error Unknown property
      unknownProp: 5,
    },
  ],
};
```

--------------------------------

### Add @context to Schema.org Types with WithContext

Source: https://context7.com/google/schema-dts/llms.txt

Use WithContext<T> to add a required '@context' property to any Schema.org type T. The '@context' value must exactly match the URL used during typings generation. This is essential for embedding JSON-LD in HTML.

```typescript
import type {Organization, Person, WithContext} from 'schema-dts';

// Person with context
const person: WithContext<Person> = {
  '@context': 'https://schema.org',
  '@type': 'Person',
  name: 'Grace Hopper',
  birthDate: '1906-12-09',
  awards: [
    'Presidential Medal of Freedom',
    'National Medal of Technology and Innovation',
  ],
};

// Organization with context — '@context' must be exactly 'https://schema.org'
const org: WithContext<Organization> = {
  '@context': 'https://schema.org',
  '@type': 'Organization',
  name: 'Acme Corp',
  url: 'https://acme.com',
  logo: 'https://acme.com/logo.png',
  sameAs: ['https://twitter.com/acme', 'https://linkedin.com/company/acme'],
};

// Type error: wrong context URL
// @ts-expect-error
const bad: WithContext<Person> = {'@context': 'https://google.com', '@type': 'Person'};
```

```typescript
// Helper to serialize safely for injection into HTML
function safeJsonLd(data: WithContext<import('schema-dts').Thing>): string {
  return JSON.stringify(data)
    .replace(/</g, '\u003C')
    .replace(/>/g, '\u003E')
    .replace(/&/g, '\u0026')
    .replace(/'/g, '\u0027');
}
// <script type="application/ld+json">${safeJsonLd(person)}</script>
```

--------------------------------

### Safely Serialize JSON-LD for HTML Injection

Source: https://github.com/google/schema-dts/blob/main/README.md

A utility function to serialize JSON-LD data into a string suitable for embedding within an HTML `<script>` tag. It escapes characters that could break out of the tag or cause XSS vulnerabilities.

```typescript
function safeJsonLd(data: WithContext<Thing>): string {
  return JSON.stringify(data)
    .replace(/</g, '\u003C')
    .replace(/>/g, '\u003E')
    .replace(/&/g, '\u0026')
    .replace(/'/g, '\u0027');
}

// Use in HTML:
// <script type="application/ld+json">${safeJsonLd(product)}</script>
```

--------------------------------

### MergeLeafTypes<T> - Combine Schema.org Leaf Types

Source: https://context7.com/google/schema-dts/llms.txt

Use MergeLeafTypes to combine multiple concrete Schema.org leaf types into a single type. The '@type' property will be a tuple of string literals matching the input order, and properties will be the intersection of all leaf members. This is useful for JSON-LD nodes with multiple @type values.

```typescript
import type {
  MergeLeafTypes,
  ProductLeaf,
  SoftwareApplicationLeaf,
  WithContext,
} from 'schema-dts';

// Dual-typed product + software node
const app: WithContext<MergeLeafTypes<[ProductLeaf, SoftwareApplicationLeaf]>> = {
  '@context': 'https://schema.org',
  '@type': ['Product', 'SoftwareApplication'],  // tuple order must match type order
  name: 'My App',
  offers: {
    '@type': 'Offer',
    price: 89,
    priceCurrency: 'USD',
    availability: 'https://schema.org/InStock',
  },
  operatingSystem: 'Any',   // from SoftwareApplication
};

// Type error: tuple order swapped
const bad: MergeLeafTypes<[ProductLeaf, SoftwareApplicationLeaf]>['@type'] = [
  // @ts-expect-error Wrong order
  'SoftwareApplication',
  // @ts-expect-error Wrong order
  'Product',
];

// Type error: union alias used instead of concrete leaf type
// @ts-expect-error Use ProductLeaf, not Product
type Wrong = MergeLeafTypes<[import('schema-dts').Product, SoftwareApplicationLeaf]>;

```

--------------------------------

### IdReference - Typed @id Stub for Cross-Referencing

Source: https://context7.com/google/schema-dts/llms.txt

IdReference is a type alias for { '@id': string }. It allows nodes to be defined once with an '@id' and referenced by IRI elsewhere in the document, useful for creating graphs with cross-references.

```typescript
import type {Graph, IdReference} from 'schema-dts';

// IdReference used as a property value
const ref: IdReference = {'@id': 'https://my.site/#alyssa'};

// Graph with cross-references
const doc: Graph = {
  '@context': 'https://schema.org',
  '@graph': [
    {
      '@type': 'Person',
      '@id': 'https://my.site/#alice',
      name: 'Alice',
      knows: {'@id': 'https://my.site/#bob'},  // IdReference
    },
    {
      '@type': 'Person',
      '@id': 'https://my.site/#bob',
      name: 'Bob',
      knows: {'@id': 'https://my.site/#alice'}, // IdReference back
    },
  ],
};

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.