SchemaRender.Generator 1.0.0

SchemaRender.NET

A developer-friendly ASP.NET Core library for adding Schema.org structured data (JSON-LD) to server-rendered pages.

Installation

Install the ASP.NET Core integration package (includes the core library):

dotnet add package SchemaRender.AspNetCore

Optionally, add the source generator for custom schema generation:

dotnet add package SchemaRender.Generator

Quick Start

1. Register Services

In your Program.cs:

builder.Services.AddSchemaRender();

2. Add Tag Helper

In _ViewImports.cshtml:

@addTagHelper *, SchemaRender.AspNetCore

3. Render in Layout

In _Layout.cshtml:

<head>
    
    <schema-render />
</head>

4. Add Schemas to Pages

public class RecipePage : SchemaPageModel
{
    public void OnGet()
    {
        Schema.Add(new RecipeSchema
        {
            Name = "Best Lasagna Ever",
            CookTime = TimeSpan.FromMinutes(45),
            PrepTime = TimeSpan.FromMinutes(30),
            RecipeIngredient = ["pasta", "ricotta", "mozzarella", "sauce"]
        });
    }
}

Usage Patterns

Using the Source Generator

Define schemas with attributes and let the generator create the implementation:

[SchemaType("Recipe")]
public partial class RecipeSchema
{
    public required string Name { get; init; }
    public TimeSpan? CookTime { get; init; }
    public TimeSpan? PrepTime { get; init; }

    [SchemaProperty(NestedType = "Person")]
    public string? Author { get; init; }

    public IReadOnlyList<string>? RecipeIngredient { get; init; }
}

The generator creates an optimized ISchema implementation automatically.

Hand-Written Schemas

Implement ISchema directly for full control:

public sealed class ArticleSchema : ISchema
{
    public required string Headline { get; init; }
    public DateTimeOffset? DatePublished { get; init; }

    public void Write(Utf8JsonWriter w)
    {
        w.WriteStartObject();
        w.WriteString("@context", "https://schema.org");
        w.WriteString("@type", "Article");
        w.WriteString("headline", Headline);

        if (DatePublished is not null)
            w.WriteString("datePublished", DatePublished.Value.ToString("O"));

        w.WriteEndObject();
    }
}

Dependency Injection

Inject ISchemaContext directly in pages or controllers:

public class ProductPage : PageModel
{
    public void OnGet([FromServices] ISchemaContext schema)
    {
        schema.Add(new ProductSchema { Name = "Widget" });
    }
}

HtmlHelper Extensions

Use Razor syntax with the HtmlHelper extension:

@inject ISchemaContext Schema

@{
    Schema.Add(new ArticleSchema
    {
        Headline = "My Post",
        DatePublished = DateTimeOffset.Now
    });
}

<head>
    @Html.RenderSchemas()
</head>

Built-in Schemas

The library includes ready-to-use implementations of the following schemas:

Source Generator Attributes

[SchemaType("TypeName")]

Marks a partial class for schema generation:

[SchemaType("LocalBusiness")]
public partial class LocalBusinessSchema { }

[SchemaProperty]

Customizes property serialization:

[SchemaProperty(Name = "dateCreated", NestedType = "Person")]
public string? Author { get; init; }

[SchemaIgnore]

Excludes a property from the generated output:

[SchemaIgnore]
public string? InternalId { get; init; }

Supported Types

Special Property Handling

Address Properties

Properties like StreetAddress, AddressLocality, PostalCode, etc. are automatically nested as PostalAddress:

public string? StreetAddress { get; init; }
public string? AddressLocality { get; init; }
public string? PostalCode { get; init; }

Generates:

{
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "123 Main St",
    "addressLocality": "New York",
    "postalCode": "10001"
  }
}

Geo Coordinates

Latitude and Longitude properties are automatically nested as GeoCoordinates:

public double? Latitude { get; init; }
public double? Longitude { get; init; }

Generates:

{
  "geo": {
    "@type": "GeoCoordinates",
    "latitude": 40.7128,
    "longitude": -74.0060
  }
}

Performance

SchemaRender is optimized for production use:

• No reflection at runtime (source-generated code)
• No intermediate strings or DOM manipulation
• No JSON parsing or serialization round-trips
• Direct streaming to response with Utf8JsonWriter
• Zero allocations in hot paths

Architecture

Your Razor Page
  │
  │  Schema.Add(new RecipeSchema {...})
  ▼
ISchemaContext (Scoped per request)
  │
  │  Collects all schemas for the request
  ▼
<schema-render /> Tag Helper
  │
  │  SchemaRenderer.Render(context)
  ▼
Utf8JsonWriter
  │
  │  Direct byte[] → Response Stream
  ▼
<script type="application/ld+json">...</script>

Requirements

• .NET 8.0 or later
• ASP.NET Core 8.0 or later

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE.txt file for details.

Links

• NuGet Package
• GitHub Repository
• Report Issues
• Schema.org Documentation