---
title: "Deduping Nodes"
description: "Automatic Schema.org node deduplication by @id. Add multiple nodes of same type with custom IDs, replace vs merge strategies."
canonical_url: "https://unhead.unjs.io/docs/schema-org/guides/core-concepts/deduping-nodes"
last_updated: "2026-08-04T00:15:50.755Z"
---

Schema.org nodes are deduplicated by their resolved ID key, not by `@type`. Helpers with a stable default ID, such as `defineWebPage()`, merge repeated definitions. Helpers with generated numbered IDs can create several nodes of the same type.

## How does node deduplication work?

Several helpers use a stable default `@id` so related nodes can refer to them. For example, `defineOrganization()` creates the primary identity node:

```ts
import { defineOrganization, useSchemaOrg } from '@unhead/schema-org/@framework'

useSchemaOrg([
  defineOrganization() // generates the primary node with an #identity ID
])
```

`defineWebPage()` can then link to that identity:

```ts
import { defineWebPage, useSchemaOrg } from '@unhead/schema-org/@framework'

useSchemaOrg([
  defineWebPage() // can link to the #identity node
])
```

For IDs containing a fragment, Unhead uses the final `#...` fragment as the graph key. Two absolute IDs that end in the same fragment therefore identify the same node, even if their origins or paths differ. Use distinct final fragments for distinct nodes.

## How do I add multiple nodes of the same type?

A stable default `@id` causes repeated definitions to merge. Provide a distinct `@id` to create a separate node:

```ts
import { defineOrganization, useSchemaOrg } from '@unhead/schema-org/@framework'

useSchemaOrg([
  defineOrganization({
    '@id': '#some-company'
  })
])
```

## How do I replace a node instead of merging?

Use `tagDuplicateStrategy: 'replace'` to fully replace a node instead of merging properties:

```ts
import { defineOrganization, useSchemaOrg } from '@unhead/schema-org/@framework'

useSchemaOrg([
  defineOrganization({
    '@id': '#some-company',
    'name': 'Bar Company',
    'url': 'https://bar.com',
  }),
])

useSchemaOrg([
  defineOrganization({
    '@id': '#some-company',
    'name': 'Foo Company',
  })
], {
  tagDuplicateStrategy: 'replace'
})

// Replaced!
// {
//   '@id': 'https://example.com/#/schema/organization/#some-company',
//   name: 'Foo Company',
// }
```

The default merge is recursive. Later scalar values replace earlier values, nested objects merge, and `@type` arrays are deduplicated. Merged `itemListElement` arrays are sorted by their existing positions and then renumbered from 1. Use `replace` when those merge rules are not appropriate for the node.