SemanticTypeModel.EFCore 4.0.0

SemanticTypeModel Package Suite

This README is shared by all SemanticTypeModel.* NuGet packages because the packages are designed, versioned, and tested as one tightly coupled suite.

Version alignment

Use the same exact version for every SemanticTypeModel.* package in your application. Mixing SemanticTypeModel package versions is unsupported.

Generator/analyzer packages are part of that rule too. The compile-time semantic manifest requires exact producer/consumer suite-version alignment.

Choose packages by scenario

SemanticTypeModel.Configuration.Generators is not part of the current package suite.

SemanticTypeModel.Abstractions and SemanticTypeModel.Core provide shared model/runtime contracts used by the suite. Applications normally start from the scenario packages rather than selecting internal package layers first.

Minimal model

using SemanticTypeModel.DotNet;

[SemanticType(SemanticTypeRole.Entity)]
[SemanticMutable]
public sealed class Customer
{
    [SemanticKey]
    [SemanticImmutable]
    public required string Id { get; init; }

    public required string Name { get; init; }
}

With SemanticTypeModel.Generators, build the project and consume the generated provider:

using SemanticTypeModel.Generated;

TypeSchemaModel model = AppSemanticTypeModel.Create();

Lifecycle mutability is optional. No mutability attribute means STM makes no lifecycle-mutability claim.

Configure

Common generator settings include:

• generated namespace/provider name;
• discovery mode and namespace filters;
• internal type/member inclusion;
• naming policy;
• key inference;
• technical-description requirements;
• System.Text.Json metadata import.

General relationship inference is not a current generator capability.

See the complete configuration reference.

JSON Schema semantic annotations

SemanticTypeModel.JsonSchema exports Draft 2020-12 and can preserve selected STM-only semantics under one optional x-stm object:

role
aggregateRoot
mutability
technicalDescription
keys
unit
ui

JSON Schema import and JSON Editor compatibility modes are not supported current APIs.

EF Core application

SemanticTypeModel.EFCore.Generators emits composable IEntityTypeConfiguration<TEntity> implementations for explicitly selected semantic models. Applications own DbContext composition and unrelated/manual entities.

The model assembly's semantic manifest is ephemeral compile-time transport. Model and EF generator packages must use the same exact SemanticTypeModel suite version.

Diagnose

If generation or projection fails:

• Troubleshooting — symptom-oriented fixes;
• Diagnostics — diagnostic IDs and fixes;
• target guides below — target-specific limitations and policies.

Target guides

• Using SemanticTypeModel
• Core semantics
• JSON Schema
• EF Core
• System.Text.Json
• Configuration / Options
• Power BI
• Projection capabilities

Package roles

Important boundaries

SemanticTypeModel defines semantic meaning and target projection defaults; applications own global target infrastructure composition.

For example:

• EF Core remains responsible for providers/migrations/database lifecycle; applications own their DbContext, manual EF configuration, and target-specific relationships;
• System.Text.Json serializer contexts remain application-owned;
• Power BI service publishing/authentication remains outside local metadata projection;
• JSON Schema is an export target, not a canonical authoring source.

See Compatibility for current breaking boundaries.