Umbraco.Community.SchemeWeaver 1.0.0-beta

Umbraco.Community.SchemeWeaver

Map Umbraco Content Types to Schema.org types and automatically generate JSON-LD structured data for your pages. SchemeWeaver provides a backoffice 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

• 500+ Schema.org types -- discovers every type in the Schema.NET library at startup (Article, Product, FAQPage, Event, Person, Organisation, and hundreds more)
• Auto-mapping with confidence scores -- suggests property mappings using exact matching, synonym dictionaries, and substring matching, each with a transparency score so you can verify suggestions
• Seven source types -- pull values from the current node, a static value, the parent node, an ancestor of a specific type, a sibling node, block content, or nested complex types
• Transforms -- strip HTML, convert to absolute URL, or format dates before output
• Backoffice dashboard -- bulk view and manage all content type mappings from the Settings section
• Workspace view -- edit the Schema.org mapping directly from the Content Type editor
• Entity actions -- right-click a Content Type to map it or generate a new one from a schema
• Content Type generation -- scaffold a new Umbraco document type from any Schema.org type, with properties pre-grouped into Content, SEO, and Metadata tabs
• Delivery API integration -- JSON-LD is automatically indexed and available via the schemaOrg field in API responses
• Tag helper -- drop <scheme-weaver content="@Model" /> into any Razor template to render the JSON-LD script tag
• Inherited schemas -- mark a mapping as inherited and it outputs on all descendant pages (e.g. Organisation schema on the homepage cascading site-wide)
• Automatic block traversal -- BlockList/BlockGrid elements with their own schema mappings are automatically rendered as separate JSON-LD blocks, zero configuration needed
• BreadcrumbList auto-generation -- a BreadcrumbList JSON-LD block is automatically generated from the content's ancestor hierarchy
• @id for AI discoverability -- each schema output includes an @id set to the content's absolute URL
• Localisation -- all UI strings use Umbraco's localisation system

Requirements

• Umbraco 17+
• .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.

How it works

The mapping model

Each mapping connects one Umbraco Content Type to one Schema.org type:

Content Type: blogPost
       maps to
Schema.org Type: BlogPosting

Within that mapping, individual property mappings define where each schema property gets its value:

Source types explained

Auto-mapping algorithm

When you map a content type to a schema type, the auto-mapper suggests property assignments using three tiers:

1. Exact match (100% confidence) -- property alias matches schema property name exactly (case-insensitive)
2. Synonym match (80% confidence) -- uses a built-in dictionary of common aliases:
   • name matches title, heading, pageTitle, nodeName
   • description matches metaDescription, excerpt, summary
   • articleBody matches content, bodyText, richText, mainContent
   • image matches heroImage, mainImage, thumbnail, featuredImage
   • datePublished matches publishDate, createDate, articleDate
   • ...and 20+ more synonym groups
3. Partial match (50% confidence) -- schema property name appears as a substring in the Umbraco property alias (e.g., name matches authorName)

Unmatched schema properties appear with 0% confidence so you can configure them manually.

JSON-LD generation

At runtime (on publish or page request), the JsonLdGenerator service:

1. Looks up the mapping for the content type
2. Creates a Schema.NET object (e.g., BlogPosting)
3. For each property mapping, resolves the value using the configured source type
4. Applies any transforms (strip HTML, format date, make URL absolute)
5. Sets the value on the Schema.NET object using reflection and implicit type operators
6. Serialises to JSON-LD

The generated output looks like:

{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "10 Tips for Better SEO",
  "author": {
    "@type": "Person",
    "name": "Jane Smith"
  },
  "datePublished": "2024-01-15",
  "articleBody": "Full article content here..."
}

Usage

Option 1: Tag helper (server-rendered sites)

In any Razor template or view:

@addTagHelper *, Umbraco.Community.SchemeWeaver

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

This renders <script type="application/ld+json"> tags with the generated JSON-LD (main schema, BreadcrumbList, inherited ancestor schemas, and auto-discovered block element schemas). If the content type has no mapping or the mapping is disabled, nothing is rendered.

Option 2: Delivery API (headless sites)

JSON-LD is automatically indexed when content is published. Fetch it from the Delivery API response:

const response = await fetch('/umbraco/delivery/api/v2/content/item/my-blog-post');
const data = await response.json();

// JSON-LD is in the schemaOrg field
const jsonLd = data.properties.schemaOrg;
if (jsonLd) {
  const script = document.createElement('script');
  script.type = 'application/ld+json';
  script.textContent = jsonLd;
  document.head.appendChild(script);
}

Option 3: Direct service injection

@inject IJsonLdGenerator JsonLdGenerator

@{
    var jsonLd = JsonLdGenerator.GenerateJsonLdString(Model);
    if (!string.IsNullOrEmpty(jsonLd))
    {
        <script type="application/ld+json">@Html.Raw(jsonLd)</script>
    }
}

Backoffice UI

Dashboard

Navigate to Settings > Schema.org Mappings to see all content types with their mapping status:

• Mapped content types show the Schema.org type, property count, and action buttons (Edit, Preview, Delete)
• Unmapped content types have a "Map" button to start the mapping flow
• Search and filter content types by name or alias

Mapping flow

1. Click Map on an unmapped content type
2. Schema Picker modal opens -- browse or search 500+ Schema.org types, grouped by parent type
3. Select a type and click Select
4. Property Mapping modal opens -- auto-mapped suggestions appear with confidence badges:
   • High (green, 80%+) -- very likely correct
   • Medium (amber, 50%+) -- probable match, worth checking
   • Low (red, <50%) -- needs manual review
5. Adjust source types and values as needed
6. Click Generate Preview to see the JSON-LD output
7. Click Save to persist the mapping

Content Type generation

From the dashboard or via entity action, you can generate a new Umbraco Content Type from any Schema.org type:

1. Select a Schema.org type
2. Choose which properties to include
3. SchemeWeaver creates the Content Type with:
   • Properties mapped to appropriate editors (Textstring, Rich Text, Date Picker, etc.)
   • Properties grouped into Content, SEO, and Metadata tabs
   • The Schema.org mapping pre-configured

Database

SchemeWeaver creates two tables on first run via Umbraco's migration system:

SchemeWeaverSchemaMapping

SchemeWeaverPropertyMapping

API reference

All endpoints are under /umbraco/management/api/v1/schemeweaver and require backoffice authentication.

Schema types

Content types

Mappings

Content type generation

Architecture

Umbraco Backoffice
    |
    v
SchemeWeaver Dashboard / Modals / Workspace View (Lit Web Components)
    |
    v
SchemeWeaverServerDataSource (fetch wrapper)
    |
    v
SchemeWeaverApiController (Management API)
    |
    v
SchemeWeaverService (orchestrator)
    |
    +---> SchemaTypeRegistry (singleton, scans Schema.NET assembly)
    +---> SchemaMappingRepository (NPoco, reads/writes database)
    +---> SchemaAutoMapper (suggests property mappings)
    +---> JsonLdGenerator (produces JSON-LD from IPublishedContent)
    +---> ContentTypeGenerator (creates Umbraco content types)

Runtime Output:
    JsonLdGenerator -----> TagHelper (<scheme-weaver> in Razor)
    JsonLdGenerator -----> SchemaJsonLdContentIndexHandler (Delivery API)

Development

Prerequisites

• .NET 10 SDK
• Node.js 22+

Build

# Full solution (backend + TestHost)
dotnet build

# Frontend (from App_Plugins/SchemeWeaver/)
cd src/Umbraco.Community.SchemeWeaver/App_Plugins/SchemeWeaver
npm install
npm run build    # builds to ../../wwwroot/dist/

Test

# C# unit tests (215 tests)
dotnet test

# Frontend unit + component tests
cd src/Umbraco.Community.SchemeWeaver/App_Plugins/SchemeWeaver
npm test

TestHost

A runnable Umbraco 17 instance is included for local development and testing:

dotnet run --project src/SchemeWeaver.TestHost

Login at http://localhost:5000/umbraco with admin@test.com / SecurePass1234.

Pack

dotnet pack src/Umbraco.Community.SchemeWeaver/Umbraco.Community.SchemeWeaver.csproj \
  --configuration Release --output ./artifacts

Licence

MIT -- see LICENSE.