<?xml version="1.0" encoding="utf-8"?>
<topic id="SerializationAttributes" revisionNumber="1">
  <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">

    <introduction>
      <para>Attributes can be used to control how Json.NET serializes and deserializes .NET objects.</para>

<list class="bullet">
  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonObjectAttribute</codeEntityReference> - Placed on classes to control how they should be serialized as a JSON object.</para></listItem>
  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonArrayAttribute</codeEntityReference> - Placed on collections to control how they should be serialized as a JSON array.</para></listItem>
  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonDictionaryAttribute</codeEntityReference> - Placed on dictionaries to control how they should be serialized as a JSON object.</para></listItem>
  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference> - Placed on fields and properties to control how they should be serialized as a property in a JSON object.</para></listItem>
  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonConverterAttribute</codeEntityReference> - Placed on either classes or fields and properties to specify which JsonConverter should be used during serialization.</para></listItem>
  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonExtensionDataAttribute</codeEntityReference> - Placed on a collection field or property to deserialize properties with no matching class member into the specified collection and write values during serialization.</para></listItem>
  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonConstructorAttribute</codeEntityReference> - Placed on a constructor to specify that it should be used to create the class during deserialization.</para></listItem>
</list>

    </introduction>
    
    <section>
      <title>Standard .NET Serialization Attributes</title>
      <content>
        <para>As well as using the built-in Json.NET attributes, Json.NET also looks for the <codeEntityReference>T:System.SerializableAttribute</codeEntityReference>
        (if IgnoreSerializableAttribute on DefaultContractResolver is set to false)
        <codeEntityReference>T:System.Runtime.Serialization.DataContractAttribute</codeEntityReference>,
        <codeEntityReference>T:System.Runtime.Serialization.DataMemberAttribute</codeEntityReference>,
        and <codeEntityReference>T:System.NonSerializedAttribute</codeEntityReference> and attributes when determining how JSON is to be serialized and deserialized.
        </para>

<alert class="note">
  <para>Json.NET attributes take precedence over standard .NET serialization attributes (e.g. if both JsonPropertyAttribute
  and DataMemberAttribute are present on a property and both customize the name,
  the name from JsonPropertyAttribute will be used).</para>
</alert>        

<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializationAttributes" title="Serialization Attributes Example" />
        
      </content>
    </section>
    
    <section>
      <title>Json.NET Serialization Attributes</title>
        <sections>
    <section>
      <title>JsonObjectAttribute</title>
      <content>
        <para>The MemberSerialization flag on this attribute specifies whether member serialization is opt-in
        (a member must have the JsonProperty or DataMember attribute to be serialized), opt-out (everything is
        serialized by default but can be ignored with the JsonIgnoreAttribute, Json.NET's default behavior) or
        fields (all public and private fields are serialized and properties are ignored).</para>
        <para>Json.NET serializes .NET classes that implement IEnumerable as a JSON array populated with the
        IEnumerable values. Placing the <codeEntityReference>T:Newtonsoft.Json.JsonObjectAttribute</codeEntityReference>
        overrides this behavior and forces the serializer to serialize the class's fields and properties.</para>
        <para>The <codeEntityReference>T:System.Runtime.Serialization.DataContractAttribute</codeEntityReference>
        can be used as substitute for JsonObjectAttribute. The DataContractAttribute will default member
        serialization to opt-in.</para>
      </content>
    </section>
        
    <section>
      <title>JsonArrayAttribute/JsonDictionaryAttribute</title>
      <content>
        <para>The <codeEntityReference>T:Newtonsoft.Json.JsonArrayAttribute</codeEntityReference> and
        <codeEntityReference>T:Newtonsoft.Json.JsonDictionaryAttribute</codeEntityReference> are used to specify
        whether a class is serialized as that collection type.</para>
        <para>The collection attributes have options to customize the JsonConverter, type name handling, and reference handling that are applied to collection items.</para>
      </content>
    </section>
        
    <section>
      <title>JsonPropertyAttribute</title>
      <content>
        <para>JsonPropertyAttribute has a number of uses:</para>
        
<list class="bullet">
  <listItem><para>By default, the JSON property will have the same name as the .NET property. This attribute allows the name to be customized.</para></listItem>
  <listItem><para>JsonPropertyAttribute indicates that a property should be serialized when member serialization is set to opt-in.</para></listItem>
  <listItem><para>It includes non-public properties in serialization and deserialization.</para></listItem>
  <listItem><para>It can be used to customize type name, reference, null, and default value handling for the property value.</para></listItem>
  <listItem><para>It can be used to customize the property's collection items JsonConverter, type name handling, and reference handling.</para></listItem>
</list>
        
        <para> The DataMemberAttribute can be used as a substitute for JsonPropertyAttribute.</para>
        
      </content>
    </section>
        
    <section>
      <title>JsonIgnoreAttribute</title>
      <content>
        <para>Excludes a field or property from serialization.</para>
        <para>The <codeEntityReference>T:System.NonSerializedAttribute</codeEntityReference> can be used as a substitute for JsonIgnoreAttribute.</para>
      </content>
    </section>
        
    <section>
      <title>JsonConverterAttribute</title>
      <content>
        <para>The <codeEntityReference>T:Newtonsoft.Json.JsonConverterAttribute</codeEntityReference> specifies which
        <codeEntityReference>T:Newtonsoft.Json.JsonConverter</codeEntityReference> is used to convert an object.</para>
        <para>The attribute can be placed on a class or a member. When placed on a class, the JsonConverter
        specified by the attribute will be the default way of serializing that class. When the attribute is
        on a field or property, then the specified JsonConverter will always be used to serialize that value.</para>
        <para>The priority of which JsonConverter is used is member attribute, then class attribute, and finally
        any converters passed to the JsonSerializer.</para>

<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\JsonConverterAttributeProperty.cs" region="Types" title="JsonConverterAttribute Property Example" />
       
        <para>This example shows the JsonConverterAttribute being applied to a property.</para>
                
        <para>To apply a JsonConverter to the items in a collection, use either <codeEntityReference>T:Newtonsoft.Json.JsonArrayAttribute</codeEntityReference>,
        <codeEntityReference>T:Newtonsoft.Json.JsonDictionaryAttribute</codeEntityReference> or
        <codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference>
        and set the ItemConverterType property to the converter type you want to use.</para>
      </content>
    </section>
        
    <section>
      <title>JsonExtensionDataAttribute</title>
      <content>
        <para>The <codeEntityReference>T:Newtonsoft.Json.JsonExtensionDataAttribute</codeEntityReference> instructs the
        <codeEntityReference>T:Newtonsoft.Json.JsonSerializer</codeEntityReference> to deserialize properties with no matching field or property
        on the type into the specified collection. During serialization the values in this collection are written back to the instance's JSON object.</para>
        <para>This example shows the JsonExtensionDataAttribute being applied to a field, unmatched JSON properties being added to the field's collection during deserialization.</para>
        <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\DeserializeExtensionData.cs" region="Types" title="Types" />
        <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\DeserializeExtensionData.cs" region="Usage" title="Usage" />
      </content>
    </section>
        
    <section>
      <title>JsonConstructorAttribute</title>
      <content>
        <para>The <codeEntityReference>T:Newtonsoft.Json.JsonConstructorAttribute</codeEntityReference> instructs the
        <codeEntityReference>T:Newtonsoft.Json.JsonSerializer</codeEntityReference> to use a specific constructor when deserializing a class. It can be used to create a class using a parameterized constructor instead of the default constructor, or to pick which specific parameterized constructor to use if there are multiple.</para>
        <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\JsonConstructorAttribute.cs" region="Types" title="Types" />
        <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\JsonConstructorAttribute.cs" region="Usage" title="Usage" />
      </content>
    </section>
    
    </sections>
    </section>
    <relatedTopics>
      <codeEntityReference>T:Newtonsoft.Json.JsonObjectAttribute</codeEntityReference>
      <codeEntityReference>T:Newtonsoft.Json.JsonArrayAttribute</codeEntityReference>
      <codeEntityReference>T:Newtonsoft.Json.JsonDictionaryAttribute</codeEntityReference>
      <codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference>
      <codeEntityReference>T:Newtonsoft.Json.JsonConverterAttribute</codeEntityReference>
      <codeEntityReference>T:Newtonsoft.Json.JsonExtensionDataAttribute</codeEntityReference>
      <codeEntityReference>T:Newtonsoft.Json.JsonConstructorAttribute</codeEntityReference>
    </relatedTopics>
  </developerConceptualDocument>
</topic>