title | description | ms.date | zone_pivot_groups | no-loc | dev_langs | helpviewer_keywords | ms.topic | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
How to customize property names and values with System.Text.Json |
Learn how to customize property names and values when serializing with System.Text.Json in .NET. |
10/16/2023 |
dotnet-version |
|
|
|
how-to |
By default, property names and dictionary keys are unchanged in the JSON output, including case. Enum values are represented as numbers. And properties are serialized in the order they're defined. However, you can customize these behaviors by:
- Specifying specific serialized property names.
- Using a built-in naming policy, such as camelCase, snake_case, or kebab-case, for property names and dictionary keys.
- Using a custom naming policy for property names and dictionary keys.
- Serializing enum values as strings, with or without a naming policy.
- Configuring the order of serialized properties.
Note
The web default naming policy is camel case.
For other scenarios that require special handling of JSON property names and values, you can implement custom converters.
To set the name of individual properties, use the [JsonPropertyName] attribute.
Here's an example type to serialize and resulting JSON:
:::code language="csharp" source="snippets/how-to/csharp/WeatherForecast.cs" id="WFWithPropertyNameAttribute"::: :::code language="vb" source="snippets/how-to/vb/WeatherForecast.vb" id="WFWithPropertyNameAttribute":::
{
"Date": "2019-08-01T00:00:00-07:00",
"TemperatureCelsius": 25,
"Summary": "Hot",
"Wind": 35
}
The property name set by this attribute:
- Applies in both directions, for serialization and deserialization.
- Takes precedence over property naming policies.
- Doesn't affect parameter name matching for parameterized constructors.
The following table shows the built-in naming policies and how they affect property names.
Naming policy | Description | Original property name | Converted property name |
---|---|---|---|
xref:System.Text.Json.JsonNamingPolicy.CamelCase | First word starts with a lower case character. Successive words start with an uppercase character. |
TempCelsius |
tempCelsius |
xref:System.Text.Json.JsonNamingPolicy.KebabCaseLower* | Words are separated by hyphens. All characters are lowercase. |
TempCelsius |
temp-celsius |
xref:System.Text.Json.JsonNamingPolicy.KebabCaseUpper* | Words are separated by hyphens. All characters are uppercase. |
TempCelsius |
TEMP-CELSIUS |
xref:System.Text.Json.JsonNamingPolicy.SnakeCaseLower* | Words are separated by underscores. All characters are lowercase. |
TempCelsius |
temp_celsius |
xref:System.Text.Json.JsonNamingPolicy.SnakeCaseUpper* | Words are separated by underscores. All characters are uppercase. |
TempCelsius |
TEMP_CELSIUS |
* Available in .NET 8 and later versions.
The following example shows how to use camel case for all JSON property names by setting xref:System.Text.Json.JsonSerializerOptions.PropertyNamingPolicy?displayProperty=nameWithType to xref:System.Text.Json.JsonNamingPolicy.CamelCase?displayProperty=nameWithType:
:::code language="csharp" source="snippets/how-to/csharp/RoundTripCamelCasePropertyNames.cs" id="Serialize"::: :::code language="vb" source="snippets/how-to/vb/RoundTripCamelCasePropertyNames.vb" id="Serialize":::
Here's an example class to serialize and JSON output:
:::code language="csharp" source="snippets/how-to/csharp/WeatherForecast.cs" id="WFWithPropertyNameAttribute"::: :::code language="vb" source="snippets/how-to/vb/WeatherForecast.vb" id="WFWithPropertyNameAttribute":::
{
"date": "2019-08-01T00:00:00-07:00",
"temperatureCelsius": 25,
"summary": "Hot",
"Wind": 35
}
The naming policy:
- Applies to serialization and deserialization.
- Is overridden by
[JsonPropertyName]
attributes. This is why the JSON property nameWind
in the example is not camel case.
Note
None of the built-in naming policies support letters that are surrogate pairs. For more information, see dotnet/runtime issue 90352.
To use a custom JSON property naming policy, create a class that derives from xref:System.Text.Json.JsonNamingPolicy and override the xref:System.Text.Json.JsonNamingPolicy.ConvertName%2A method, as shown in the following example:
:::code language="csharp" source="snippets/how-to/csharp/UpperCaseNamingPolicy.cs"::: :::code language="vb" source="snippets/how-to/vb/UpperCaseNamingPolicy.vb":::
Then set the xref:System.Text.Json.JsonSerializerOptions.PropertyNamingPolicy?displayProperty=nameWithType property to an instance of your naming policy class:
:::code language="csharp" source="snippets/how-to/csharp/RoundtripPropertyNamingPolicy.cs" id="Serialize"::: :::code language="vb" source="snippets/how-to/vb/RoundtripPropertyNamingPolicy.vb" id="Serialize":::
Here's an example class to serialize and JSON output:
:::code language="csharp" source="snippets/how-to/csharp/WeatherForecast.cs" id="WFWithPropertyNameAttribute"::: :::code language="vb" source="snippets/how-to/vb/WeatherForecast.vb" id="WFWithPropertyNameAttribute":::
{
"DATE": "2019-08-01T00:00:00-07:00",
"TEMPERATURECELSIUS": 25,
"SUMMARY": "Hot",
"Wind": 35
}
The JSON property naming policy:
- Applies to serialization and deserialization.
- Is overridden by
[JsonPropertyName]
attributes. This is why the JSON property nameWind
in the example is not upper case.
If a property of an object to be serialized is of type Dictionary<string,TValue>
, the string
keys can be converted using a naming policy, such as camel case. To do that, set xref:System.Text.Json.JsonSerializerOptions.DictionaryKeyPolicy?displayProperty=nameWithType to your desired naming policy. The following example uses the CamelCase
naming policy:
:::code language="csharp" source="snippets/how-to/csharp/SerializeCamelCaseDictionaryKeys.cs" id="Serialize"::: :::code language="vb" source="snippets/how-to/vb/SerializeCamelCaseDictionaryKeys.vb" id="Serialize":::
Serializing an object with a dictionary named TemperatureRanges
that has key-value pairs "ColdMinTemp", 20
and "HotMinTemp", 40
would result in JSON output like the following example:
{
"Date": "2019-08-01T00:00:00-07:00",
"TemperatureCelsius": 25,
"Summary": "Hot",
"TemperatureRanges": {
"coldMinTemp": 20,
"hotMinTemp": 40
}
}
Naming policies for dictionary keys apply to serialization only. If you deserialize a dictionary, the keys will match the JSON file even if you set xref:System.Text.Json.JsonSerializerOptions.DictionaryKeyPolicy?displayProperty=nameWithType to a non-default naming policy.
:::zone pivot="dotnet-8-0"
By default, enums are serialized as numbers. To serialize enum names as strings, use the xref:System.Text.Json.Serialization.JsonStringEnumConverter or xref:System.Text.Json.Serialization.JsonStringEnumConverter%601 converter. Only xref:System.Text.Json.Serialization.JsonStringEnumConverter%601 is supported by the Native AOT runtime.
:::zone-end
:::zone pivot="dotnet-7-0,dotnet-6-0"
By default, enums are serialized as numbers. To serialize enum names as strings, use the xref:System.Text.Json.Serialization.JsonStringEnumConverter converter.
:::zone-end
For example, suppose you need to serialize the following class that has an enum:
:::code language="csharp" source="snippets/how-to/csharp/WeatherForecast.cs" id="WFWithEnum"::: :::code language="vb" source="snippets/how-to/vb/WeatherForecast.vb" id="WFWithEnum":::
If the Summary is Hot
, by default the serialized JSON has the numeric value 3:
{
"Date": "2019-08-01T00:00:00-07:00",
"TemperatureCelsius": 25,
"Summary": 3
}
The following sample code serializes the enum names instead of the numeric values, and converts the names to camel case:
:::code language="csharp" source="snippets/how-to/csharp/RoundtripEnumAsString.cs" id="Serialize"::: :::code language="vb" source="snippets/how-to/vb/RoundtripEnumAsString.vb" id="Serialize":::
The resulting JSON looks like the following example:
{
"Date": "2019-08-01T00:00:00-07:00",
"TemperatureCelsius": 25,
"Summary": "hot"
}
The built-in xref:System.Text.Json.Serialization.JsonStringEnumConverter can deserialize string values as well. It works with or without a specified naming policy. The following example shows deserialization using CamelCase
:
:::code language="csharp" source="snippets/how-to/csharp/RoundtripEnumAsString.cs" id="Deserialize"::: :::code language="vb" source="snippets/how-to/vb/RoundtripEnumAsString.vb" id="Deserialize":::
:::zone pivot="dotnet-8-0"
You can also specify the converter to use by annotating your enum with xref:System.Text.Json.Serialization.JsonConverterAttribute. The following example shows how to specify the xref:System.Text.Json.Serialization.JsonStringEnumConverter%601 (available in .NET 8 and later versions) by using the xref:System.Text.Json.Serialization.JsonConverterAttribute attribute. For example, suppose you need to serialize the following class that has an enum:
:::code language="csharp" source="snippets/how-to/csharp/WeatherForecast.cs" id="WFWithConverterEnum":::
The following sample code serializes the enum names instead of the numeric values:
:::code language="csharp" source="snippets/how-to/csharp/RoundtripEnumUsingConverterAttribute.cs" id="Serialize":::
The resulting JSON looks like the following example:
{
"Date": "2019-08-01T00:00:00-07:00",
"TemperatureCelsius": 25,
"Precipitation": "Sleet"
}
To use the converter with source generation, see Serialize enum fields as strings.
:::zone-end
By default, properties are serialized in the order in which they're defined in their class. The [JsonPropertyOrder]
attribute lets you specify the order of properties in the JSON output from serialization. The default value of the Order
property is zero. Set Order
to a positive number to position a property after those that have the default value. A negative Order
positions a property before those that have the default value. Properties are written in order from the lowest Order
value to the highest. Here's an example:
:::code language="csharp" source="snippets/how-to-6-0/csharp/PropertyOrder.cs":::