<?xml version="1.0" encoding="utf-8"?>
<topic id="DatesInJSON" revisionNumber="1">
  <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
    <!--
    <summary>
      <para>Optional summary abstract</para>
    </summary>
    -->
    <introduction>
      <para>DateTimes in JSON are hard.</para>
      <para>The problem comes from the <externalLink>
<linkText>JSON spec</linkText>
<linkUri>http://www.ietf.org/rfc/rfc4627.txt</linkUri>
<linkTarget>_blank</linkTarget>
</externalLink> 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.</para>
    </introduction>
    <!-- Add one or more top-level section elements.  These are collapsible.
         If using <autoOutline />, add an address attribute to identify it
         and specify a title so that it can be jumped to with a hyperlink. -->
    <section>
      <title>Dates and Json.NET</title>
      <content>
        <!-- Uncomment this to create a sub-section outline
        <autoOutline /> -->
        <para>The default format used by Json.NET is the <externalLink>
<linkText>ISO 8601 standard</linkText>
<linkUri>http://en.wikipedia.org/wiki/ISO_8601</linkUri>
<linkTarget>_blank</linkTarget>
</externalLink>: <codeInline>"2012-03-19T07:22Z"</codeInline>.</para>
        <para>Prior to Json.NET 4.5 dates were written using the Microsoft
        format: <codeInline>"\/Date(1198908717056)\/"</codeInline>. 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
        <codeEntityReference>T:Newtonsoft.Json.DateFormatHandling</codeEntityReference>
        setting to MicrosoftDateFormat.</para>
        <para>The <codeEntityReference>T:Newtonsoft.Json.DateTimeZoneHandling</codeEntityReference> setting can be
        used to convert a DateTime's <codeEntityReference>T:System.DateTimeKind</codeEntityReference> when serializing. For example set
        DateTimeZoneHandling to Utc to serialize all DateTimes as UTC dates. Note that this setting does not effect DateTimeOffsets.</para>
        <para>If your dates don't follow the ISO 8601 standard, then the DateFormatString setting can be used to customize the format of
        	date strings that are read and written using .NET's <externalLink>
<linkText>custom date and time format syntax</linkText>
<linkUri>https://msdn.microsoft.com/en-us/library/8kb3ddd4.aspx</linkUri>
<linkTarget>_blank</linkTarget>
</externalLink>.</para>
      </content>
    </section>
    <section>
      <title>DateTime JsonConverters</title>
      <content>
        <!-- Uncomment this to create a sub-section outline
        <autoOutline /> -->
        <para>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.</para>
        
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializingDatesInJson" title="DateTime JsonConverters Example" />        
        
        <para>Simply pass the JsonConverter you wish to use to the Json.NET
        serializer.</para>
      </content>
    </section>
    <section>
      <title>JavaScriptDateTimeConverter</title>
      <content>
        <para>The JavaScriptDateTimeConverter class is one of the two DateTime
        JsonConverters that come with Json.NET. This converter serializes a
        DateTime as a <externalLink>
<linkText>JavaScript Date object</linkText>
<linkUri>http://msdn.microsoft.com/en-us/library/cd9w2te4.aspx</linkUri>
<linkTarget>_blank</linkTarget>
</externalLink>: <codeInline>new Date(1234656000000)</codeInline></para>
        <para>Technically this is invalid JSON according to the spec, but all
        browsers and some JSON frameworks, including Json.NET, support it.</para>
      </content>
    </section>
    <section>
      <title>IsoDateTimeConverter</title>
      <content>
      <alert class="note">
  <para>From Json.NET 4.5 and onwards dates are written using the ISO 8601
        format by default, and using this converter is unnecessary.</para>
</alert>
        <para>IsoDateTimeConverter serializes a DateTime to an <externalLink>
<linkText>ISO 8601</linkText>
<linkUri>http://en.wikipedia.org/wiki/ISO_8601</linkUri>
<linkTarget>_blank</linkTarget>
</externalLink> formatted
        string: <codeInline>"2009-02-15T00:00:00Z"</codeInline></para>        
        <para>The IsoDateTimeConverter class has a property, DateTimeFormat, to
        further customize the formatted string.</para>
      </content>
    </section>
    <relatedTopics>
      <codeEntityReference>T:Newtonsoft.Json.DateFormatHandling</codeEntityReference>
      <codeEntityReference>T:Newtonsoft.Json.DateTimeZoneHandling</codeEntityReference>
      <codeEntityReference>T:Newtonsoft.Json.Converters.JavaScriptDateTimeConverter</codeEntityReference>
      <codeEntityReference>T:Newtonsoft.Json.Converters.IsoDateTimeConverter</codeEntityReference>
    </relatedTopics>
  </developerConceptualDocument>
</topic>