# 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](/foundation/0.19.0/guides/presentation-localization/#request-zone-json-and-hostbackground-controls-0190),
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.
