SemanticTypeModel.DotNet 6.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 v3 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]
    [SemanticLogicalType("CustomerId")]
    [SemanticImmutable]
    public required Guid 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. Logical Type is optional property metadata over an ordinary scalar and is never inferred from CLR wrapper shape.

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 6.0 boundaries and capabilities

The 6.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.

CLR single-value wrappers are not automatically inferred as scalars by STM or its projections. Strong Scalar canonical semantics and SemanticLiteralKind.StrongIdentifier are removed in the 6.0 boundary. Applications that use strongly typed CLR IDs own their target-specific conversions/integration.

The STM-configured JSON Schema contract is bounded and one-way: supported output validates against the schema, without a promise of bidirectional serializer/schema equivalence. Native scalar fidelity is preserved across the projection suite: Binary uses Base64 JSON with schema contentEncoding: base64, System.Uri uses uri-reference by default, and raw Json is not restricted to object values.

An ordinary scalar property may opt into a projection-neutral Logical Type name with [SemanticLogicalType("CustomerId")]. The name is metadata only: it does not change CLR, JSON, EF, LINQ, TestData, or Power BI representation. Names must be valid and same-name properties in one model must use the same scalar type.

SemanticTypeModel.TestData provides deterministic constraint-aware semantic graph generation and the typed model.TestData().Generate<T>() / GenerateMany<T>() facade. Random mode needs no terminology profile. Optional model-bound Semantic Terminology Profiles provide synthetic property/Logical-Type candidates, while programmatic generators can supply application-specific scalar values. Public CLR materialization uses supported constructors and members and never infers scalar meaning from wrapper shapes. Invalid explicit custom candidates and materialization failures are reported with TestData diagnostics; built-in regex synthesis remains unsupported.

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
logicalType (property metadata)

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

For System.Text.Json runtime integration, use JsonSerializerOptions.AddSemanticTypeModelJson(model). This configures modeled semantic Entity polymorphism without requiring a generated serializer context. Register all models before first serializer use; explicit application polymorphism contracts remain unchanged.

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/capability guides below — target-specific limitations and policies.

Target and capability guides

• Using SemanticTypeModel
• Core semantics
• JSON Schema
• EF Core
• System.Text.Json
• Power BI
• Projection capabilities
• Constraint-aware test data

Package roles

The aligned release suite contains exactly these eleven packages. All eleven 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, SemanticTypeModel.SystemTextJson, and SemanticTypeModel.TestData. 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.