From d988312c37692e7cdd626b1a38ce7607e18423cb Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Tue, 20 Mar 2012 01:08:30 +1300 Subject: -Documentation --- Doc/DatesInJSON.html | 11 +++++++-- Doc/SerializationSettings.html | 38 ++++++++++++++++++++++++++++++- Src/Newtonsoft.Json/DateFormatHandling.cs | 2 +- 3 files changed, 47 insertions(+), 4 deletions(-) diff --git a/Doc/DatesInJSON.html b/Doc/DatesInJSON.html index fab328c..64e8c47 100644 --- a/Doc/DatesInJSON.html +++ b/Doc/DatesInJSON.html @@ -17,7 +17,12 @@

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 for dates is the same one used by Microsoft: "\/Date(1198908717056)\/". You can read more about it here.

+

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.

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.

@@ -72,7 +77,9 @@

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.

+

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.

diff --git a/Doc/SerializationSettings.html b/Doc/SerializationSettings.html index d11a80f..8092790 100644 --- a/Doc/SerializationSettings.html +++ b/Doc/SerializationSettings.html @@ -19,7 +19,43 @@ JSON. These can also be used with the methods on JsonConvert via the JsonSerializerSettings overloads.

-

MissingMemberHandling

+

DateFormatHandling

+

DateFormatHandling controls how dates are serialized.

+ + + + + + + + + + + + + + + +
+ Member + + Description +
+ IsoDateFormat + +
+ By default Json.NET writes dates in the ISO 8601 format, e.g. "2012-03-21T05:40Z". +
+
+
+ MicrosoftDateFormat + +
+ Dates are written in the Microsoft JSON format, e.g. "\/Date(1198908717056)\/". +
+
+
+

MissingMemberHandling

MissingMemberHandling controls how missing members, e.g. JSON contains a property that isn't a member on the object, are handled during deserialization.

diff --git a/Src/Newtonsoft.Json/DateFormatHandling.cs b/Src/Newtonsoft.Json/DateFormatHandling.cs index 47efaf4..e2fed58 100644 --- a/Src/Newtonsoft.Json/DateFormatHandling.cs +++ b/Src/Newtonsoft.Json/DateFormatHandling.cs @@ -6,7 +6,7 @@ namespace Newtonsoft.Json public enum DateFormatHandling { /// - /// Dates are written in the ISO 8061 format, e.g. "2012-03-21T05:40Z". + /// Dates are written in the ISO 8601 format, e.g. "2012-03-21T05:40Z". /// IsoDateFormat, /// -- cgit v1.2.3