---
title: "Conventions: Deserialization"
url: "https://docs.ravendb.net/6.2/client-api/configuration/deserialization"
version: "6.2"
language: "csharp"
---

# Conventions: Deserialization

> Client language: C#. Also available for [Java](https://docs.ravendb.net/6.2/client-api/configuration/deserialization.java.md).
>
> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

> **Note**
>
> - The C# client deserializes documents loaded from the server into entities using the
>   [Newtonsoft.Json](https://www.newtonsoft.com/json/help/html/SerializingJSON.htm) library (also known as Json.NET).
> - Use the [conventions](https://docs.ravendb.net/6.2/client-api/configuration/conventions.md) described in this article
>   to customize the deserialization (e.g., to preserve document properties that your entity class does not define).
> - In this article:
>   - [CustomizeJsonDeserializer](#customizejsondeserializer)
>   - [DeserializeEntityFromBlittable](#deserializeentityfromblittable)
>   - [PreserveDocumentPropertiesNotFoundOnModel](#preservedocumentpropertiesnotfoundonmodel)
>   - [DefaultRavenSerializationBinder](#defaultravenserializationbinder)
>   - [Number Deserialization](#number-deserialization)

## CustomizeJsonDeserializer {#customizejsondeserializer}

- The client uses `JsonSerializer` objects of the [Newtonsoft.Json](https://www.newtonsoft.com/json/help/html/SerializingJSON.htm)
  library to **deserialize** documents loaded from the server into entities.
- Use the `CustomizeJsonDeserializer` convention to register an action that modifies only the `JsonSerializer` objects
  used to load documents (e.g., to keep a property's default value when the loaded document holds `null` for this property).
  ```csharp
  Conventions =
  {
      Serialization = new NewtonsoftJsonSerializationConventions
      {
          CustomizeJsonDeserializer = serializer => throw new CodeOmitted()
      }
  }
  ```
- Note that an action registered using [CustomizeJsonSerializer](https://docs.ravendb.net/6.2/client-api/configuration/serialization.md#customizejsonserializer)
  also applies when loading documents, and runs before the `CustomizeJsonDeserializer` action.  
  A [converter](https://docs.ravendb.net/6.2/client-api/configuration/serialization.md#adding-a-converter) registered using `CustomizeJsonSerializer`
  therefore does not need to be registered using `CustomizeJsonDeserializer` as well.

## DeserializeEntityFromBlittable {#deserializeentityfromblittable}

Use the `DeserializeEntityFromBlittable` convention to customize entity
deserialization from a blittable JSON.

```csharp
Conventions =
{
    Serialization = new NewtonsoftJsonSerializationConventions
    {
        DeserializeEntityFromBlittable = (type, blittable) => throw new CodeOmitted()
    }
}
```

## PreserveDocumentPropertiesNotFoundOnModel {#preservedocumentpropertiesnotfoundonmodel}

- Some document properties are not deserialized to an object.
- Set the `PreserveDocumentPropertiesNotFoundOnModel` convention to `true`
  to **preserve** such properties when the document is saved.
- Set the `PreserveDocumentPropertiesNotFoundOnModel` convention to `false`
  to **remove** such properties when the document is saved.
- Default: `true`

```csharp
Conventions =
{
    PreserveDocumentPropertiesNotFoundOnModel = true
}
```

## DefaultRavenSerializationBinder {#defaultravenserializationbinder}

Use the `DefaultRavenSerializationBinder` convention and its methods to
prevent gadgets from running RCE (Remote Code Execution) attacks while
data is deserialized by the client.

Read about this security convention and maintaining deserialization security
[here](https://docs.ravendb.net/6.2/client-api/security/deserialization-security.md).

## Number Deserialization {#number-deserialization}

- RavenDB client supports all common numeric value types (including `int`, `long`,
  `double`, `decimal`, etc.) out of the box.
- Note that although deserialization of `decimals` is fully supported, there are
  [server side limitations](https://docs.ravendb.net/6.2/server/kb/numbers-in-ravendb.md) to numbers in this range.
- Other number types, like `BigInteger`, must be handled using a [converter](https://docs.ravendb.net/6.2/client-api/configuration/serialization.md#adding-a-converter).

## See also

- [Conventions](https://docs.ravendb.net/6.2/client-api/configuration/conventions.md)
- [Load Balance &amp; Failover](https://docs.ravendb.net/6.2/client-api/configuration/load-balance/overview.md)
- [Serialization](https://docs.ravendb.net/6.2/client-api/configuration/serialization.md)
- [Deserialization Security](https://docs.ravendb.net/6.2/client-api/security/deserialization-security.md)
- [Document Identifiers](https://docs.ravendb.net/6.2/client-api/document-identifiers/working-with-document-identifiers.md)
- [Global ID Generation](https://docs.ravendb.net/6.2/client-api/configuration/identifier-generation/global.md)
- [Type-specific ID](https://docs.ravendb.net/6.2/client-api/configuration/identifier-generation/type-specific.md)
- [Document Store](https://docs.ravendb.net/6.2/client-api/what-is-a-document-store.md)
