Serialization Guide

The Json.NET serializer can serialize a wide variety of .NET objects. This guide looks at how it works at a high level and in more detail.

Summary

At a high level, the Json.NET serializer will convert primitive .NET values into primitive JSON values, .NET arrays and collections to JSON arrays and everything else to JSON objects.

Json.NET will throw an error if it encounters incorrect JSON when deserializing a value. For example if the serializer encounters a JSON property with an array of values and the type of matching .NET property is not a collection then an error will be thrown, and vice-versa.

Complex Types

Primitive Types

Breakdown of Type Serialization

Objects

.NET types that don't fall into any other category listed below (i.e. aren't lists, dictionaries, dynamic, implement ISerializable, etc) are serialized as JSON objects.

By default types are serialized in opt-out mode. What that means is all public fields and properties with getters are automatically serialized to JSON and members that shouldn't be serialized are opted-out using the JsonIgnoreAttribute. To serialize private members the JsonPropertyAttribute can be placed on private fields and properties or the DefaultMembersSearchFlags can be changed on DefaultContractResolver to change how members are serialized on all types.

Types can also be serialized using opt-in mode. Only properties and fields that have a JsonPropertyAttribute or DataMemberAttribute on them will be serialized. Opt-in mode for an object is specified using the JsonObjectAttribute on the class.

Finally types can be serialized using a fields mode. All fields, both public and private, are serialized and properties are ignored. This can be specified by setting MemberSerialization.Fields on a type with the JsonObject attribute or by the .NET Serializable attribute and setting IgnoreSerializableAttribute on DefaultContractResolver to false.

IEnumerable, Lists and Arrayss

.NET lists (types that inherit from IEnumerable) and .NET arrays are converted to JSON arrays. Because JSON arrays only support a range of values and not properties, any additional properties and fields declared on .NET collections are not serialized. In situations where a JSON array is not wanted the JsonObjectAttribute can be placed on a .NET type that implements IEnumerable to force the type to be serialized as a JSON object instead.

JsonArrayAttribute has options on it to customize the JsonConverter, type name handling and reference handling that are applied to collection items.

Note that if TypeNameHandling or PreserveReferencesHandling has been enabled for JSON arrays on the serializer then JSON arrays are wrapped it a containing object. The object will have the type name/reference properties and a $values property which will have the collection data.

When deserializing if a member is typed as the interface IList<T> then it will be deserialized as a List<T>.

Read more about serializing collections here: Serializing Collections

Dictionarys and Hashtables

.NET dictionaries (types that inherit from IDictionary) are converted to JSON objects. Note that only the dictionary name/values will be written to the JSON object when serializing and properties on the JSON object will be added to the dictionary's name/values when deserializing. Additional members on the .NET dictionary are ignored during serialization.

JsonDictionaryAttribute has options on it to customize the JsonConverter, type name handling and reference handling that are applied to collection items.

When deserializing if a member is typed as the interface IDictionary<TKey, TValue> then it will be deserialized as a Dictionary<TKey, TValue>.

Read more about serializing collections here: Serializing Collections

Untyped Objects

.NET properties on a class that don't specify a type (i.e. they are just object) are serialized as usual. When untyped properties are deserialized the serializer has no way to know what type to create (unless type name handling is enabled and the JSON contains the type names).

For these untyped properties the Json.NET serializer will read the JSON into LINQ to JSON objects and set them to the property. JObject will be created for JSON objects, JArray will be created for JSON arrays and JValue for primitive JSON values.

Dynamic

There are two different usages of dynamic (introduced in .NET 4) in .NET. The first are .NET properties with a type of dynamic. Dynamic proeprties behave like properties declared as object, any value can be assigned to it, but the difference being that properties and methods can be called on a dynamic property without casting. In Json.NET dynamic properties are serialized and deserialized exactly the same as untyped objects: because dynamic isn't an actual type Json.NET falls back to deserializing the JSON as LINQ to JSON objects.

The second usage of dynamic in .NET are classes that implement IDynamicMetaObjectProvider. This interface lets the implementor create dynamic objects that intercept the property and method calls on an object and use them. ExpandoObject is a good example of a dynamic object.

Dynamic objects are serialized as JSON objects. A property is written for every member name returned by DynamicMetaObject.GetDynamicMemberNames.

When deserializing dynamic objects the serializer first attempts to set JSON property values on a normal .NET member with the matching name. If no .NET member is found with the property name then the serializer will call SetMember on the dynamic object. Because there is no type information for dynamic members on a dynamic object the values assigned to them will be LINQ to JSON objects

ISerializable

Types that implement ISerializable are serialized as JSON objects. When serializing only the values returned from ISerializable.GetObjectData are used; members on the type are ignored. When deserializing the constructor with a SerializationInfo and StreamingContext is called, passing the JSON object's values.

In situations where this behavior is not wanted the JsonObjectAttribute can be placed on a .NET type that implements ISerializable to force it to be serialized as a normal JSON object.

LINQ to JSON

LINQ to JSON types (e.g. JObject, JArray) are automatically serialized and deserialized to their equivalent JSON when encountered by the Json.NET serializer.

JsonConverter

Serialization of values that are convertible by a JsonConverter (i.e. CanConvert returns true for its type) is completely overridden by the JsonConverter. The test to see whether a value can be converted by a JsonSerializer takes precedence over all other tests.

JsonConverters can be defined and specified in a number of places: in an attribute on a member, in an attribute on a class and added to the JsonSerializer's converters collection. The priority of which JsonConverter is used is the JsonConverter defined by attribute on a member then the JsonConverter defined by an attribute on a class and finally any converters passed to the JsonSerializer.