👁 Image
Umbraco.Community.SchemeWeaver.uSync 1.4.4

👁 SchemeWeaver

Umbraco.Community.SchemeWeaver

Map Umbraco Content Types to Schema.org types and automatically generate JSON-LD structured data for your pages.

👁 NuGet
👁 License

👋 Heads-up — I'm building this one in public. SchemeWeaver is usable today, but I'm still dialling in the editor UX and a few of the sharper edges. Expect small behavioural and UI changes between releases while that settles down. Every change (breaking or otherwise) gets called out in the release notes so you can see what's coming before you upgrade.

If something bites you, confuses you, or you just have a suggestion — please open an issue. I genuinely want the feedback, especially the "this UX is weird" kind. The package is better for every issue that gets logged.

SchemeWeaver provides a document type editor UI for configuring mappings, an auto-mapper that suggests property assignments, and runtime JSON-LD generation that works with both server-rendered templates and the headless Delivery API.

Why structured data?

Search engines use JSON-LD to understand page content. A blog post tagged as BlogPosting with a headline, author, and datePublished can appear as a rich result in Google, Bing, and other search engines. Manually maintaining JSON-LD scripts is tedious and error-prone -- SchemeWeaver automates it from your existing content.

Features

• 780 Schema.org types -- discovers every type in the Schema.NET.Pending library at startup, including pending types like RealEstateListing
• Auto-mapping with confidence scores -- suggests property mappings using exact matching, synonym dictionaries, and substring matching
• Smart property UI -- shows mapped properties first, with an "Add property" combobox to add more schema properties
• Seven source types -- pull values from the current node, a static value, the parent, an ancestor, a sibling, block content, or nested complex types
• Transforms -- strip HTML, convert to absolute URL, or format dates before output
• Content Type generation -- scaffold a new Umbraco document type from any Schema.org type
• Language variants -- culture-aware JSON-LD generation for multi-language sites. When content varies by culture, SchemeWeaver pulls the correct localised values and auto-populates inLanguage with the BCP 47 culture code. Works across server-rendered templates, the Delivery API, and the backoffice preview
• Delivery API integration -- dedicated /umbraco/delivery/api/v2/schemeweaver/json-ld endpoint returns the per-page JSON-LD blocks, culture-aware, cached in-process with event-driven invalidation on publish/unpublish/move/delete
• Tag helper -- drop <scheme-weaver content="@Model" /> into any Razor template; the tag helper reads the current culture from Umbraco's IVariationContextAccessor automatically
• Inherited schemas -- mark a mapping as inherited and it outputs on all descendant pages
• BreadcrumbList -- automatically generated from the content's ancestor hierarchy

Requirements

• Umbraco 17 & 18
• .NET 10

Installation

dotnet add package Umbraco.Community.SchemeWeaver

No additional configuration needed. The package registers all services, creates its database tables on first run, and adds the backoffice UI automatically.

Umbraco 17 vs 18

Umbraco 18 made a binary-breaking change to IPublishedContent, so a single assembly cannot run on both majors. SchemeWeaver therefore ships one package per Umbraco major from the same source:

NuGet picks the right build for your project automatically when you constrain to a major; the -umbraco18 builds are held as prereleases until Umbraco 18.0.0 (and uSync 18.0.0) ship as stable.

Optional: uSync Integration

To sync schema mappings between environments via uSync:

dotnet add package Umbraco.Community.SchemeWeaver.uSync --prerelease

The uSync addon follows the same per-major scheme (1.4.x for Umbraco 17, 1.4.x-umbraco18 for Umbraco 18). The Umbraco 18 build depends on the uSync 18 release candidate and stays a prerelease until uSync 18.0.0 is stable. See for details.

Quick Start

1. Add the tag helper

In your master layout (e.g. _Layout.cshtml):

@addTagHelper *, Umbraco.Community.SchemeWeaver

<head>
 ...
 <scheme-weaver content="@Model" />
</head>

2. Map your content types

1. Open any document type in Settings > Document Types
2. Click the Schema.org tab
3. Click Map to Schema.org and select a type (e.g. Product, Article, Event)
4. Review the auto-suggested property mappings in the modal and click Save
5. Publish content -- JSON-LD appears in the page source

3. Headless / Delivery API

JSON-LD is served from a dedicated endpoint — fetch it in parallel with your content request and inject the strings as <script type="application/ld+json"> tags:

const response = await fetch(
 '/umbraco/delivery/api/v2/schemeweaver/json-ld/by-route?route=/my-blog-post',
 { headers: { 'Api-Key': process.env.UMBRACO_DELIVERY_API_KEY! } },
);
const { schemaOrg }: { schemaOrg: string[] } = await response.json();

Responses are cached in-process and invalidated automatically by publish/unpublish/move/delete notifications, so the cache stays fresh without manual busting. The array is ordered: inherited ancestor schemas → BreadcrumbList → main page schema → block-element schemas. See for the full endpoint surface, Next.js example, and the opt-out for BreadcrumbList when your front-end builds its own.

Pre-1.3 consumers who read schemaOrg from properties.schemaOrg on the content response: that was never actually wired up (index handlers feed Examine, not the response body). Use the dedicated endpoint above.

4. Language variants

No extra configuration needed. If your content type varies by culture, SchemeWeaver automatically:

• Pulls property values in the requested culture (tag helper reads the current VariationContext; the Delivery API handler is called once per culture)
• Populates inLanguage with the BCP 47 culture code (e.g. "de-DE") unless you've explicitly mapped inLanguage yourself
• Generates culture-correct URLs for @id and breadcrumb links

Mappings stay invariant -- the same mapping applies to all cultures. You don't need per-language mappings; SchemeWeaver resolves the right value at generation time.

The backoffice JSON-LD preview tab automatically follows the workspace variant selector, so switching to German in the editor shows the German JSON-LD output.

Documentation

• -- installation, tag helper, first mapping
• -- full mapping workflow
• -- source types, transforms, confidence tiers
• -- BlockList/BlockGrid mapping, nested types, wrapInType
• -- scaffold document types from Schema.org
• -- headless integration
• -- custom property resolvers, replacing core services
• -- sync schema mappings between environments
• -- inherited schemas, BreadcrumbList, troubleshooting
• -- REST API endpoints

How it works

Each mapping connects one Umbraco Content Type to one Schema.org type. Within that mapping, individual property mappings define where each schema property gets its value:

The auto-mapper suggests assignments using three confidence tiers:

• High (100%) -- exact property name match
• Medium (80%) -- synonym match (e.g. title to name, bodyText to articleBody)
• Low (50%) -- substring match

The generated output:

{
 "@context": "https://schema.org",
 "@type": "BlogPosting",
 "headline": "10 Tips for Better SEO",
 "author": {
 "@type": "Person",
 "name": "Jane Smith"
 },
 "datePublished": "2024-01-15",
 "inLanguage": "en-US"
}

Notes

• Block content nested types -- complex Schema.org properties (e.g. acceptedAnswer, reviewRating) require a wrapper type. The auto-mapper pre-configures this for common patterns (FAQ, Product, Recipe). For custom types, see the .
• Media picker edge cases -- complex multi-crop scenarios with specific crop aliases may need manual URL configuration. See .

Releasing

Maintainer notes — shipping a new version to NuGet and the Umbraco Marketplace:

1. Ensure NUGET_API_KEY is set in Settings → Secrets and variables → Actions (a single API key with "Push new packages and package versions" scope on Umbraco.Community.SchemeWeaver*).
2. Tag the commit you want to ship: git tag v1.0.0-beta.4 && git push origin v1.0.0-beta.4.
3. The Release to NuGet workflow builds, tests, packs and pushes the package to nuget.org, and opens a matching GitHub release.
4. The Umbraco Marketplace listing is automatic — it discovers packages on nuget.org that carry the umbraco-marketplace tag (already set in the csproj) and usually updates within 24 hours.

To publish an out-of-band build without tagging, use the workflow's "Run workflow" button on the Actions tab and type the version explicitly.

Contributing

Contributions are very welcome — bug reports, fixes, docs, new property resolvers, extra auto-mapper synonyms, whole new features. Small PRs are fine.

Getting set up

# C#
dotnet build
dotnet test

# Frontend
cd src/Umbraco.Community.SchemeWeaver/App_Plugins/SchemeWeaver
npm install
npm run build
npm test
npm run test:msw # component tests with MSW handlers
npm run test:mocked-backoffice # Playwright drives the real backoffice UI with MSW — needs Umbraco-CMS clone
npm run test:e2e # Playwright against a running Umbraco + .env
npm run test:screenshots # regenerate the docs screenshots (opt-in)

# Test host with 100+ sample content types
dotnet run --project src/Umbraco.Community.SchemeWeaver.TestHost

Note: The TestHost is purely for testing schema mappings and structured data generation. It is not intended as a base site or starter kit.

Read for architecture, DI wiring, and naming conventions.

Tests

Please add tests for behavioural changes, and a regression test for bug fixes. CI runs the full suite on every push.

For backoffice UI changes, npm run test:mocked-backoffice verifies manifest wiring, workspace-view conditions, and modal plumbing without a running Umbraco; npm run test:e2e against a real instance is still the only thing that catches issues across the full .NET + backoffice stack.

Using an AI assistant

AI tools (Claude, Codex, Copilot, Cursor, etc.) are welcome to help. The rules are short:

• You review it. Read every line before committing. You're accountable for the PR, not the assistant.

• MIT-compatible only. Don't submit code copied from incompatible sources.

• Add tests, same as any other contribution.

• For UI work, install the Umbraco Backoffice Skills and add umbraco/Umbraco-CMS (src/Umbraco.Web.UI.Client) and umbraco/Umbraco.UI (packages/uui) as working directories so the skills can grep the canonical backoffice source — see the skills repo for setup. Also run the umbraco-extension-reviewer agent on UI changes.

• Tag the commit. When an assistant materially helped, add a git trailer at the bottom of the commit message so we can see which model was used:

  Assisted-by: Claude:claude-opus-4-6
  

  Format is Assisted-by: <agent>:<model> [optional tools], e.g. Assisted-by: Copilot:gpt-5 playwright. Just leave a blank line before it, or use git commit --trailer "Assisted-by=...". Basic tools (git, dotnet, npm, editors) don't need listing. If your tool already adds a Co-authored-by: trailer for the assistant automatically, that's fine too — just don't bother adding both.

• Don't add Signed-off-by on a human's behalf. Only the human submitter can sign off their own contribution.

Licence

MIT — see . By submitting a pull request you agree to license your contribution under the same terms.

Author

Oliver Picton / Enjoy Digital