Supported collection types in System.Text.Json

This article gives an overview of which collections are supported for serialization and deserialization. System.Text.Json.JsonSerializer supports a collection type for serialization if it:

  • Derives from IEnumerable.
  • Contains elements that are serializable.

The serializer calls the GetEnumerator() method, and writes the elements.

Deserialization is more complicated and is not supported for some collection types.

The following sections are organized by namespace and show which types are supported for serialization and deserialization.

System.Array namespace

Type Serialization Deserialization
Single-dimensional arrays ✔️ ✔️
Multi-dimensional arrays
Jagged arrays ✔️ ✔️

System.Collections namespace

Type Serialization Deserialization
ArrayList ✔️ ✔️
BitArray ✔️
DictionaryEntry ✔️ ✔️
Hashtable ✔️ ✔️
Queue ✔️ ✔️
SortedList ✔️ ✔️
Stack ✔️ ✔️
ICollection ✔️ ✔️
IDictionary ✔️ ✔️
IEnumerable ✔️ ✔️
IList ✔️ ✔️

System.Collections.Generic namespace

Type Serialization Deserialization
Dictionary<TKey,TValue> * ✔️ ✔️
HashSet<T> ✔️ ✔️
KeyValuePair<TKey,TValue> ✔️ ✔️
LinkedList<T> ✔️ ✔️
LinkedListNode<T> ✔️
List<T> ✔️ ✔️
Queue<T> ✔️ ✔️
SortedDictionary<TKey,TValue> * ✔️ ✔️
SortedList<TKey,TValue> * ✔️ ✔️
SortedSet<T> ✔️ ✔️
Stack<T> ✔️ ✔️
IAsyncEnumerable<T>
ICollection<T> ✔️ ✔️
IDictionary<TKey,TValue> * ✔️ ✔️
IEnumerable<T> ✔️ ✔️
IList<T> ✔️ ✔️
IReadOnlyCollection<T> ✔️ ✔️
IReadOnlyDictionary<TKey,TValue> * ✔️ ✔️
IReadOnlyList<T> ✔️ ✔️
ISet<T> ✔️ ✔️
Type Serialization Deserialization
Dictionary<string, TValue> * ✔️ ✔️
HashSet<T> ✔️ ✔️
KeyValuePair<TKey,TValue> ✔️ ✔️
LinkedList<T> ✔️ ✔️
LinkedListNode<T> ✔️
List<T> ✔️ ✔️
Queue<T> ✔️ ✔️
SortedDictionary<string, TValue> * ✔️ ✔️
SortedList<string, TValue> * ✔️ ✔️
SortedSet<T> ✔️ ✔️
Stack<T> ✔️ ✔️
IAsyncEnumerable<T>
ICollection<T> ✔️ ✔️
IDictionary<string, TValue> * ✔️ ✔️
IEnumerable<T> ✔️ ✔️
IList<T> ✔️ ✔️
IReadOnlyCollection<T> ✔️ ✔️
IReadOnlyDictionary<string, TValue> * ✔️ ✔️
IReadOnlyList<T> ✔️ ✔️
ISet<T> ✔️ ✔️

* See Supported key types.

System.Collections.Immutable namespace

Type Serialization Deserialization
ImmutableArray<T> ✔️ ✔️
ImmutableDictionary<TKey,TValue> ** ✔️ ✔️
ImmutableHashSet<T> ✔️ ✔️
IImmutableList<T> ✔️ ✔️
ImmutableQueue<T> ✔️ ✔️
ImmutableSortedDictionary<TKey,TValue> ** ✔️ ✔️
ImmutableSortedSet<T> ✔️ ✔️
ImmutableStack<T> * ✔️ ✔️
IImmutableDictionary<TKey,TValue> ** ✔️ ✔️
IImmutableList<T> ✔️ ✔️
IImmutableQueue<T> ✔️ ✔️
IImmutableSet<T> ✔️ ✔️
IImmutableStack<T> * ✔️ ✔️
Type Serialization Deserialization
ImmutableArray<T> ✔️ ✔️
ImmutableDictionary<string, TValue> ** ✔️ ✔️
ImmutableHashSet<T> ✔️ ✔️
IImmutableList<T> ✔️ ✔️
ImmutableQueue<T> ✔️ ✔️
ImmutableSortedDictionary<string, TValue> ** ✔️ ✔️
ImmutableSortedSet<T> ✔️ ✔️
ImmutableStack<T> * ✔️ ✔️
IImmutableDictionary<string, TValue> ** ✔️ ✔️
IImmutableList<T> ✔️ ✔️
IImmutableQueue<T> ✔️ ✔️
IImmutableSet<T> ✔️ ✔️
IImmutableStack<T> * ✔️ ✔️

* See Support round trip for Stack<T>.

** See Supported key types.

System.Collections.Specialized namespace

Type Serialization Deserialization
BitVector32 ✔️ ❌*
HybridDictionary ✔️ ✔️
IOrderedDictionary ✔️
ListDictionary ✔️ ✔️
StringCollection ✔️
StringDictionary ✔️
NameValueCollection ✔️

* When BitVector32 is deserialized, the Data property is skipped because it doesn't have a public setter. No exception is thrown.

System.Collections.Concurrent namespace

Type Serialization Deserialization
BlockingCollection<T> ✔️
ConcurrentBag<T> ✔️
ConcurrentDictionary<TKey,TValue> ** ✔️ ✔️
ConcurrentQueue<T> ✔️ ✔️
ConcurrentStack<T> * ✔️ ✔️
Type Serialization Deserialization
BlockingCollection<T> ✔️
ConcurrentBag<T> ✔️
ConcurrentDictionary<string, TValue> ** ✔️ ✔️
ConcurrentQueue<T> ✔️ ✔️
ConcurrentStack<T> * ✔️ ✔️

* See Support round trip for Stack<T>.

** See Supported key types.

System.Collections.ObjectModel namespace

Type Serialization Deserialization
Collection<T> ✔️ ✔️
KeyedCollection<string, TValue> * ✔️
ObservableCollection<T> ✔️ ✔️
ReadOnlyCollection<T> ✔️
ReadOnlyDictionary<TKey,TValue> ✔️
ReadOnlyObservableCollection<T> ✔️

* Non-string keys are not supported.

Type Serialization Deserialization
Collection<T> ✔️ ✔️
KeyedCollection<string, TValue> * ✔️
ObservableCollection<T> ✔️ ✔️
ReadOnlyCollection<T> ✔️
ReadOnlyDictionary<string, TValue> * ✔️
ReadOnlyObservableCollection<T> ✔️

* See Supported key types.

Custom collections

Any collection type that isn't in one of the preceding namespaces is considered a custom collection. Such types include user-defined types and types defined by ASP.NET Core. For example, Microsoft.Extensions.Primitives is in this group.

All custom collections (everything that derives from IEnumerable) are supported for serialization, as long as their element types are supported.

Custom collections with deserialization support

A custom collection is supported for deserialization if it:

* See Support round trip for Stack<T>.

** See Supported key types.

Custom collections with known issues

There are known issues with the following custom collections:

For more information about known issues, see the open issues in System.Text.Json.

Supported key types

Supported types for the keys of Dictionary and SortedList types include the following:

  • Boolean
  • Byte
  • DateTime
  • DateTimeOffset
  • Decimal
  • Double
  • Enum
  • Guid
  • Int16
  • Int32
  • Int64
  • Object (Only on serialization and if the runtime type is one of the supported types in this list.)
  • SByte
  • Single
  • String
  • UInt16
  • UInt32
  • UInt64

** Non-string keys for Dictionary and SortedList types are not supported in .NET Core 3.1.

See also