SemanticTypeModel.Generators 5.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. The current ephemeral manifest schema is v2 and is not a persisted interchange format.

Choose packages by scenario

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.

Current 5.0 boundaries and capabilities

The 5.0 suite retains SemanticTypeRole.Configuration as projection-neutral meaning and retains SemanticRequiredWhen; it does not include STM-owned Configuration/Options binding or registration. The removed SemanticTypeModel.Configuration package and AddSemanticOptions<TOptions> API have no tombstone or forwarding replacement.

Use [SemanticDisplayIdentity(Order = 0)] and [SemanticAccessPath("ByCustomerNumber")] for ordered, projection-neutral recognition and locate/filter semantics. These annotations do not generate indexes, API queries, UI behavior, Power BI behavior, or relationships.

Use [SemanticStrongScalar] for an explicit readonly nominal scalar wrapper. Supported projections use its underlying scalar representation; it is not itself an Identifier, Key, Entity, ownership declaration, or one-property inference convention. The STM-configured System.Text.Json and derived JSON Schema contract is bounded and one-way: supported output validates against the schema, without a promise of bidirectional serializer/schema equivalence.

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
• Power BI
• Projection capabilities

Package roles

The 5.0.0 release suite contains exactly these ten packages. All ten must be kept at the same exact version: SemanticTypeModel.Abstractions, SemanticTypeModel.Core, SemanticTypeModel.JsonSchema, SemanticTypeModel.DotNet, SemanticTypeModel.Generators, SemanticTypeModel.DependencyInjection, SemanticTypeModel.PowerBI, SemanticTypeModel.EFCore, SemanticTypeModel.EFCore.Generators, and SemanticTypeModel.SystemTextJson. SemanticTypeModel.Configuration is not part of the suite.

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.