Serializing Dates in JSON

Json.NET - Quick Starts & API Documentation
Serializing Dates in JSON

DateTimes in JSON are hard.

The problem comes from the JSON spec itself: there is no literal syntax for dates in JSON. The spec has objects, arrays, strings, integers and floats, but it defines no standard for what a date looks like.

The default format used by Json.NET is the ISO 8601 standard: 2012-03-19T07:22Z. You can read more about it here.

Prior to Json.NET 4.5 dates were written using the Microsoft format: "\/Date(1198908717056)\/". If you want to use this format, or you want to maintain compatibility with Microsoft JSON serializers or older versions of Json.NET then change the DateFormatHandling setting to MicrosoftDateFormat.

Json.NET also has the DateTimeZoneHandling setting. This can be used to convert DateTime's kind when serializing, e.g. set DateTimeZoneHandling to Utc to serialize all DateTimes as UTC dates.

### DateTime JsonConverters

With no standard for dates in JSON, the number of possible different formats when interoping with other systems is endless. Fortunately Json.NET has a solution to deal with reading and writing custom dates: JsonConverters. A JsonConverter is used to override how a type is serialized.

    public class LogEntry

    {

      public string Details { get; set; }

      public DateTime LogDate { get; set; }

    }

    [Test]

    public void WriteJsonDates()

    {

      LogEntry entry = new LogEntry

      {

        LogDate = new DateTime(2009, 2, 15, 0, 0, 0, DateTimeKind.Utc),

        Details = "Application started."

      };

      // default as of Json.NET 4.5

      string isoJson = JsonConvert.SerializeObject(entry);

      // {"Details":"Application started.","LogDate":"2009-02-15T00:00:00Z"}

      JsonSerializerSettings microsoftDateFormatSettings = new JsonSerializerSettings

      {

        DateFormatHandling = DateFormatHandling.MicrosoftDateFormat

      };

      string microsoftJson = JsonConvert.SerializeObject(entry, microsoftDateFormatSettings);

      // {"Details":"Application started.","LogDate":"\/Date(1234656000000)\/"}

      string javascriptJson = JsonConvert.SerializeObject(entry, new JavaScriptDateTimeConverter());

      // {"Details":"Application started.","LogDate":new Date(1234656000000)}

    }

Simply pass the JsonConverter you wish to use to the Json.NET serializer.

#### JavaScriptDateTimeConverter

The JavaScriptDateTimeConverter class is one of the two DateTime JsonConverters that come with Json.NET. This converter serializes a DateTime as a JavaScript Date object.

    new Date(1234656000000)

Technically this is invalid JSON according to the spec but all browsers, and some JSON frameworks, including Json.NET, support it.

#### IsoDateTimeConverter

IsoDateTimeConverter seralizes a DateTime to an ISO 8601 formatted string. Note that since Json.NET 4.5 dates are written using the ISO 8601 format by default and using this converter is unnecessary.

    "2009-02-15T00:00:00Z"

The IsoDateTimeConverter class has a property, DateTimeFormat, to further customize the formatted string.