---
title: Bind a JSON date value
summary: Bind a request value to a `DateTime`, tolerating missing or unparseable input.
status: draft
owner: SAIF Documentation
last_reviewed: 2026-09-17
library: SAIF.Framework.Web.Mvc
reference_type: package
operation_id: OP-18
trigger: MVC model binding for a bound `DateTime` when the binder is registered
---

# Bind a JSON date value

Bind a request value to a `DateTime`, tolerating missing or unparseable input. Trigger: MVC model binding for a bound `DateTime` when the binder is registered.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-18 |
| **Trigger** | MVC model binding for a bound `DateTime` when the binder is registered |
| **Inputs** | `bindingContext.ValueProvider` value for `ModelName` |
| **Outputs** | `DateTime`, or the raw null value |
| **Primary components** | `JsonDateTimeModelBinder.BindModel(ControllerContext, ModelBindingContext)` |
| **Entry point** | `src/Web.Mvc/ModelBinders/JsonDateTimeModelBinder.cs` |

## Steps

1. When no value is found, return `new DateTime()` (`0001-01-01`) ([BR-39](../business-rules.md#br-39-missing-date-value-binds-to-datetime-default)).
2. When `value.RawValue` is null, return `value.RawValue` (null).
3. When the attempted value starts with `/`, treat it as the ASP.NET JSON date form `/Date(ms)/`: take the substring from index 6, strip the trailing `)/`, add that many milliseconds to the Unix epoch `1970-01-01`, and convert with `ToLocalTime()` ([BR-40](../business-rules.md#br-40-asp.net-json-date-form-is-converted-from-unix-epoch)).
4. Otherwise call `DateTime.TryParse`; on failure the out value remains `default(DateTime)` and is returned, so a parse failure never raises a binding error ([BR-41](../business-rules.md#br-41-unparseable-date-binds-to-the-datetime-default)).

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Model binding])
	NoVal{Value found?}
	Default([Return DateTime default])
	Null{RawValue null?}
	ReturnNull([Return null])
	Slash{Starts with /?}
	JsonDate["Parse /Date(ms)/ epoch form"]
	TryParse[DateTime.TryParse]
	EndOk([Return DateTime])
	Start --> NoVal
	NoVal -->|No| Default
	NoVal -->|Yes| Null
	Null -->|Yes| ReturnNull
	Null -->|No| Slash
	Slash -->|Yes| JsonDate
	Slash -->|No| TryParse
	JsonDate --> EndOk
	TryParse --> EndOk
```

## Failure and edge-case behavior

- No unexpected failure paths beyond argument-guard exceptions and delegated dependency behavior were identified for this operation.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

## Sources
- `src/Web.Mvc/ModelBinders/JsonDateTimeModelBinder.cs`