Skip to content
fabricators docs
On this page

Keep technical values UTC and invariant

Configure explicit process and JSON defaults independent of deployment culture and timezone.

Status: supplied in 0.15.0; 0.18.0 preserves explicit DateTimeOffset output offsets and adds an explicit UTC-only output policy. Versions 0.15.0–0.17.0 normalize both input and output to UTC. Version 0.14.0 does not supply these configuration methods. This contract is independent of machine locale/TZ.

Call FoundationRuntime.UseInvariantCulture() from Fabricators.Kernel.Common at executable entry, before constructing the host, parsing technical settings or starting workers. It sets current/default thread cultures and UI cultures to InvariantCulture. Foundation libraries do not mutate global process culture as a side effect of registering unrelated services. Deliberately localize human presentation using a requested culture; do not reuse it for hashes or storage.

Configure owned serializers with FoundationRuntime.ConfigureJson(options); for ASP.NET Minimal APIs use ConfigureHttpJsonOptions and for MVC configure its separate JSON options. Configure persistence/event serializers explicitly as well; Foundation does not rewrite existing stored payloads or fingerprints.

The configuration requires numeric JSON tokens and ISO timestamps containing Z or a numeric offset. DateTimeOffset input normalizes to UTC; its output preserves the explicit offset chosen by the handler. For example, a handler converting an instant to the resolved x-timezone: Europe/Rome can return "2026-11-17T20:45:00+01:00". Serialization preserves that value; it does not apply the request timezone to other timestamps automatically. The instant remains identical to "2026-11-17T19:45:00Z".

Products requiring UTC-only output can opt in explicitly:

csharp
FoundationRuntime.ConfigureJson(options, new JsonTimeOptions
{
    NormalizeOutputToUtc = true,
});

// ASP.NET Minimal API host configuration:
services.AddFoundationRuntimeDefaults(time => time.NormalizeOutputToUtc = true);

JsonTimeOptions is in Fabricators.Kernel.Common. Output policy is snapshotted at registration; later mutations do not change serialization. Configure before first serializer use. Reconfiguration replaces Foundation's converters without duplicating them or removing unrelated converters. For existing durable serializers, signed payloads and fingerprints, explicitly keep UTC-only output to preserve the previous wire representation before adopting this increment.

DateTime reads become UTC. DateTime output requires Kind == Utc; Local and Unspecified throw JsonException, which can fail an HTTP response at serialization. EF-loaded DateTime values can have Kind == Unspecified: do not expose those values directly. Map to DateTimeOffset at the response edge using the known storage contract and an explicit timezone, or assign UTC kind only when the stored value is demonstrably a UTC instant. Never silently label an arbitrary wall-clock value UTC. Nullable timestamps follow the same rules. Localized strings such as "1.234,56" are not monetary JSON numbers. Use decimal, explicit currency/minor-unit rules and explicit rounding; never binary floating point for ledger amounts. CSV/imports must declare their own culture and ambiguity rules; they are not technical JSON protocols.

Compare DateTimeOffset instants directly, normalize with ToUniversalTime when persisting and derive Unix timestamps from those instants. Presentation responses may retain a deliberate offset; this does not change domain/storage UTC rules. Never compare DateTime.Unspecified with UTC or infer a missing timezone from the deployment machine. TimeProvider.GetUtcNow is the source for current instants. Clock-skew policy bounds actual instants, not wall-clock text.

Business dates (invoice date, fiscal period, due date) remain DateOnly; turning them into midnight UTC changes their meaning. Recurrence uses the explicitly configured business timezone and DST rules; Cronos already converts its result to a UTC instant. Formatting/parsing technical strings must pass CultureInfo.InvariantCulture and identifier comparisons use Ordinal. JSON's built-in numeric representation is culture-independent even if a caller selects a local presentation culture.

If caching a response that has already been localized, include the resolved timezone and culture in its cache variation. Alternatively, cache neutral UTC data and perform presentation conversion after reading it from the cache. HTTP Vary alone does not partition an application's internal object cache.

No TZ mutation or invariant-globalization switch disables the platform's timezone/culture databases. Configuration must work on Windows, Linux and macOS without selecting the local machine timezone. Consumer adoption, schema/data migration and product frontend localization remain explicit operations.

Additional explicit policies (0.19.0)

Status: supplied in 0.19.0; the 0.18.0 defaults above remain unchanged. JsonTimeOptions.ConfigureTimestamps and ConfigureNumbers default to true. Disable the latter to preserve existing JsonNumberHandling when adopting date validation; disable the former for number-only configuration. A disabled switch leaves that policy untouched, rather than uninstalling earlier configuration. NumberHandling is independently configurable and defaults to Strict. This is not a culture-sensitive monetary parser.

For explicit fixed-zone serializers, OutputZone resolves a TimeZoneInfo for each DateTimeOffset write. It is mutually exclusive with NormalizeOutputToUtc. The reusable OffsetTimestampConverter retains the same strict UTC-normalized read side. Do not capture a scoped service in global serializer options. HTTP hosts should use request-zone registration, which resolves the already established presentation for each current request and rejects missing request/middleware instead of guessing a zone.

G-06: the DateTime output contract is unchanged: UTC kind writes Z, Local and Unspecified kinds throw. Prefer DateTimeOffset DTOs. For SQL Server datetime2 columns known to contain UTC instants, a consumer can explicitly apply an EF value converter/convention on those properties which reads using DateTime.SpecifyKind(value, DateTimeKind.Utc). Validate UTC on writes, document the storage invariant and exclude wall-clock/business date properties. Never apply that relabeling to arbitrary incoming values or to Local timestamps. PostgreSQL timestamptz should use its native UTC mapping. This is a consumer mapping/migration decision; Foundation does not silently rewrite an EF model.

↑ ↓ to move↵ to openSearching fabricators .NET foundation v0.19.0