The 9.0 release of System.Text.Json includes many features, primarily with a focus on JSON schema and intelligent application support. It also includes highly requested enhancements such as nullable reference type support, customizing enum member names, out-of-order metadata deserialization and customizing serialization indentation.<\/p>\n
You can try out the new features by referencing the latest build of System.Text.Json NuGet package<\/a> or the latest SDK for .NET 9<\/a>.<\/p>\n The new The resultant schema provides a specification of the JSON serialization contract for the type. As can be seen in this example, it distinguishes between nullable and non-nullable properties and populates the The generated schema can be further controlled using the Finally, users are able to apply their own transformations to generated schema nodes by specifying a Tying it all together, we can now generate a schema that incorporates This is a particularly useful component when it comes to generating schemas for .NET methods or APIs; it is being used to power ASP.NET Core’s newly released OpenAPI component and we’ve deployed it to a number of AI related libraries and applications with tool calling requirements such as Semantic Kernel, Visual Studio Copilot and the newly released Microsoft.Extensions.AI library.<\/p>\n This additionally makes it possible to read JSON from payloads that may contain trailing data that is invalid JSON:<\/p>\n When it comes to streaming deserialization, we have included a new Similarly, this setting adds enforcement on deserialization:<\/p>\n Due to how non-nullable reference types are implemented, this feature comes with an important number of limitations that users need to familiarize themselves with before turning it on. The root of the issue is that reference type nullability has no first-class representation in IL, as such the expressions If you are looking to add nullability enforcement in these cases, we recommend that you either model your type to be a struct (since they do not admit Users can turn on the It should be noted that This is because STJ treats required and non-nullable properties as orthogonal concepts. This stems from the C# language itself where you can have And optional properties that are non-nullable:<\/p>\n The same orthogonality applies to constructor parameters:<\/p>\n STJ constructor-based deserialization has historically been treating all constructor parameters as optional, as can be highlighted in the following example:<\/p>\n In .NET 9 we’re including the Users can turn on the Both the The new Certain features of System.Text.Json such as polymorphism or By default, the STJ metadata reader requires that the metadata properties This is known to create problems when needing to deserialize JSON payloads that do not originate from System.Text.Json. The new Care should be taken when enabling this flag, as it might result in over-buffering (and OOM failures) when performing streaming deserialization of very large JSON objects. This is because metadata properties must be read before<\/em> the deserialize object is instantiated, meaning that all properties preceding a The The This allows modifications to object instances that can directly influence property order:<\/p>\n The new The new For a detailed write-up of System.Text.Json performance improvements in .NET 9, please refer to the relevant section<\/a> in Stephen Toub\u2019s “Performance Improvements in .NET 9” article.<\/p>\n .NET 9 sees a large number of new features and quality of life improvements with a focus on JSON schema and intelligent application support. In total 46 pull requests<\/a> contributed to System.Text.Json during .NET 9 development. We’d like you to try the new features and give us feedback on how it improves your applications, and any usability issues or bugs that you might encounter.<\/p>\nJSON Schema Exporter<\/h2>\n
JsonSchemaExporter<\/code> class can be used to extract JSON schema<\/a> documents from .NET types using either JsonSerializerOptions<\/code> or JsonTypeInfo<\/code> instances:<\/p>\nusing System.Text.Json.Schema;\n\nJsonSerializerOptions options = JsonSerializerOptions.Default;\nJsonNode schema = options.GetJsonSchemaAsNode(typeof(Person));\nConsole.WriteLine(schema.ToString());\n\/\/{\n\/\/ \"type\": [\"object\", \"null\"],\n\/\/ \"properties\": {\n\/\/ \"Name\": { \"type\": \"string\" },\n\/\/ \"Age\": { \"type\": \"integer\" },\n\/\/ \"Address\": { \"type\": [\"string\", \"null\"], \"default\": null }\n\/\/ },\n\/\/ \"required\": [\"Name\", \"Age\"]\n\/\/}\n\nrecord Person(string Name, int Age, string? Address = null);<\/code><\/pre>\nrequired<\/code> keyword by virtue of a constructor parameter being optional or not. The schema output can be influenced by configuration specified in the JsonSerializerOptions<\/code> or JsonTypeInfo<\/code> instances:<\/p>\nJsonSerializerOptions options = new(JsonSerializerOptions.Default)\n{\n PropertyNamingPolicy = JsonNamingPolicy.KebabCaseUpper,\n NumberHandling = JsonNumberHandling.WriteAsString,\n UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow,\n};\n\nJsonNode schema = options.GetJsonSchemaAsNode(typeof(MyPoco));\nConsole.WriteLine(schema.ToString());\n\/\/{\n\/\/ \"type\": [\"object\", \"null\"],\n\/\/ \"properties\": {\n\/\/ \"NUMERIC-VALUE\": {\n\/\/ \"type\": [\"string\", \"integer\"],\n\/\/ \"pattern\": \"^-?(?:0|[1-9]\\\\d*)$\"\n\/\/ }\n\/\/ },\n\/\/ \"additionalProperties\": false\n\/\/}\n\nclass MyPoco\n{\n public int NumericValue { get; init; }\n}<\/code><\/pre>\nJsonSchemaExporterOptions<\/code> configuration type:<\/p>\nJsonSerializerOptions options = JsonSerializerOptions.Default;\nJsonSchemaExporterOptions exporterOptions = new()\n{\n \/\/ Marks root-level types as non-nullable\n TreatNullObliviousAsNonNullable = true,\n};\n\nJsonNode schema = options.GetJsonSchemaAsNode(typeof(Person), exporterOptions);\nConsole.WriteLine(schema.ToString());\n\/\/{\n\/\/ \"type\": \"object\",\n\/\/ \"properties\": {\n\/\/ \"Name\": { \"type\": \"string\" }\n\/\/ },\n\/\/ \"required\": [\"Name\"]\n\/\/}\n\nrecord Person(string Name);<\/code><\/pre>\nTransformSchemaNode<\/code> delegate. Here’s an example that incorporates text from DescriptionAttribute<\/code> annotations:<\/p>\nJsonSchemaExporterOptions exporterOptions = new()\n{\n TransformSchemaNode = (context, schema) =>\n {\n \/\/ Determine if a type or property and extract the relevant attribute provider\n ICustomAttributeProvider? attributeProvider = context.PropertyInfo is not null\n ? context.PropertyInfo.AttributeProvider\n : context.TypeInfo.Type;\n\n \/\/ Look up any description attributes\n DescriptionAttribute? descriptionAttr = attributeProvider?\n .GetCustomAttributes(inherit: true)\n .Select(attr => attr as DescriptionAttribute)\n .FirstOrDefault(attr => attr is not null);\n\n \/\/ Apply description attribute to the generated schema\n if (descriptionAttr != null)\n {\n if (schema is not JsonObject jObj)\n {\n \/\/ Handle the case where the schema is a boolean\n JsonValueKind valueKind = schema.GetValueKind();\n Debug.Assert(valueKind is JsonValueKind.True or JsonValueKind.False);\n schema = jObj = new JsonObject();\n if (valueKind is JsonValueKind.False)\n {\n jObj.Add(\"not\", true);\n }\n }\n\n jObj.Insert(0, \"description\", descriptionAttr.Description);\n }\n\n return schema;\n }\n};<\/code><\/pre>\ndescription<\/code> keyword source from attribute annotations:<\/p>\nJsonNode schema = options.GetJsonSchemaAsNode(typeof(Person), exporterOptions);\nConsole.WriteLine(schema.ToString());\n\/\/{\n\/\/ \"description\": \"A person\",\n\/\/ \"type\": [\"object\", \"null\"],\n\/\/ \"properties\": {\n\/\/ \"Name\": { \"description\": \"The name of the person\", \"type\": \"string\" }\n\/\/ },\n\/\/ \"required\": [\"Name\"]\n\/\/}\n\n[Description(\"A person\")]\nrecord Person([property: Description(\"The name of the person\")] string Name);<\/code><\/pre>\nStreaming multiple JSON documents<\/h2>\n
Utf8JsonReader<\/code> now supports reading multiple, whitespace-separated JSON documents from a single buffer or stream. By default, Utf8JsonReader<\/code> will throw an exception if it detects any non-whitespace characters that are trailing the first top-level document. This behavior can be changed using the JsonReaderOptions.AllowMultipleValues<\/code> flag:<\/p>\nJsonReaderOptions options = new() { AllowMultipleValues = true };\nUtf8JsonReader reader = new(\"null {} 1 \\r\\n [1,2,3]\"u8, options);\n\nreader.Read();\nConsole.WriteLine(reader.TokenType); \/\/ Null\n\nreader.Read();\nConsole.WriteLine(reader.TokenType); \/\/ StartObject\nreader.Skip();\n\nreader.Read();\nConsole.WriteLine(reader.TokenType); \/\/ Number\n\nreader.Read();\nConsole.WriteLine(reader.TokenType); \/\/ StartArray\nreader.Skip();\n\nConsole.WriteLine(reader.Read()); \/\/ False<\/code><\/pre>\nUtf8JsonReader reader = new(\"[1,2,3] <NotJson\/>\"u8, new() { AllowMultipleValues = true });\n\nreader.Read();\nreader.Skip(); \/\/ Success\nreader.Read(); \/\/ throws JsonReaderException<\/code><\/pre>\nJsonSerializer.DeserializeAsyncEnumerable<\/code> overload that makes streaming multiple top-level values possible. By default, DeserializeAsyncEnumerable<\/code> will attempt to stream elements that are contained in a top-level JSON array. This behavior can be toggled using the new topLevelValues<\/code> flag:<\/p>\nReadOnlySpan<byte> utf8Json = \"\"\"[0] [0,1] [0,1,1] [0,1,1,2] [0,1,1,2,3]\"\"\"u8;\nusing var stream = new MemoryStream(utf8Json.ToArray());\n\nawait foreach (int[] item in JsonSerializer.DeserializeAsyncEnumerable<int[]>(stream, topLevelValues: true))\n{\n Console.WriteLine(item.Length);\n}<\/code><\/pre>\nRespecting nullable annotations<\/h2>\n
JsonSerializer<\/code> now adds limited support for non-nullable reference type enforcement in serialization and deserialization. This can be toggled using the RespectNullableAnnotations<\/code> flag:<\/p>\n#nullable enable\nJsonSerializerOptions options = new() { RespectNullableAnnotations = true };\n\nMyPoco invalidValue = new(Name: null!);\nJsonSerializer.Serialize(invalidValue, options);\n\/\/ System.Text.Json.JsonException: The property or field 'Name'\n\/\/ on type 'MyPoco' doesn't allow getting null values. Consider\n\/\/ updating its nullability annotation. \n\nrecord MyPoco(string Name);<\/code><\/pre>\nJsonSerializerOptions options = new() { RespectNullableAnnotations = true };\nstring json = \"\"\"{\"Name\":null}\"\"\";\nJsonSerializer.Deserialize<MyPoco>(json, options);\n\/\/ System.Text.Json.JsonException: The constructor parameter 'Name'\n\/\/ on type 'MyPoco' doesn't allow null values. Consider updating\n\/\/ its nullability annotation.<\/code><\/pre>\nLimitations<\/h3>\n
MyPoco<\/code> and MyPoco?<\/code> are indistinguishable from the perspective of run-time reflection<\/a>. While the compiler will try to make up for that by emitting attribute metadata where possible<\/a>, this is restricted to non-generic member annotations that are scoped to a particular type definition. It is for this reason that the flag only validates nullability annotations that are present on non-generic properties, fields, and constructor parameters. System.Text.Json does not support nullability enforcement on<\/p>\n\n
JsonSerializer.(De)serialize<\/code> call.<\/li>\nList<string><\/code> and List<string?><\/code> types.<\/li>\nnull<\/code> values) or author a custom converter that overrides its HandleNull<\/code><\/a> property to true<\/code>.<\/p>\nFeature switch<\/h3>\n
RespectNullableAnnotations<\/code> setting globally using the System.Text.Json.Serialization.RespectNullableAnnotationsDefault<\/code> feature switch, which can be set via your project configuration:<\/p>\n<ItemGroup>\n <RuntimeHostConfigurationOption Include=\"System.Text.Json.Serialization.RespectNullableAnnotationsDefault\" Value=\"true\" \/>\n<\/ItemGroup><\/code><\/pre>\nOn the relation between nullable and optional parameters<\/h3>\n
RespectNullableAnnotations<\/code> does not extend enforcement to unspecified JSON values:<\/p>\nJsonSerializerOptions options = new() { RespectNullableAnnotations = true };\nvar result = JsonSerializer.Deserialize<MyPoco>(\"{}\", options); \/\/ No exception!\nConsole.WriteLine(result.Name is null); \/\/ True\n\nclass MyPoco\n{\n public string Name { get; set; }\n}<\/code><\/pre>\nrequired<\/code> properties that are nullable:<\/p>\nMyPoco poco = new() { Value = null }; \/\/ No compiler warnings\n\nclass MyPoco\n{\n public required string? Value { get; set; }\n}<\/code><\/pre>\nclass MyPoco\n{\n public string Value { get; set; } = \"default\";\n}<\/code><\/pre>\nrecord MyPoco(\n string RequiredNonNullable,\n string? RequiredNullable,\n string OptionalNonNullable = \"default\",\n string? OptionalNullable = \"default\");<\/code><\/pre>\nRespecting non-optional constructor parameters<\/h2>\n
var result = JsonSerializer.Deserialize<Person>(\"{}\");\nConsole.WriteLine(result); \/\/ Person { Name = , Age = 0 }\n\nrecord Person(string Name, int Age);<\/code><\/pre>\nRespectRequiredConstructorParameters<\/code> flag that changes the behavior such that non-optional constructor parameters are now treated as required:<\/p>\nJsonSerializerOptions options = new() { RespectRequiredConstructorParameters = true };\nstring json = \"\"\"{\"Optional\": \"value\"}\"\"\";\nJsonSerializer.Deserialize<MyPoco>(json, options);\n\nrecord MyPoco(string Required, string? Optional = null);\n\/\/ JsonException: JSON deserialization for type 'MyPoco' \n\/\/ was missing required properties including: 'Required'.<\/code><\/pre>\nFeature switch<\/h3>\n
RespectRequiredConstructorParameters<\/code> setting globally using the System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault<\/code> feature switch, which can be set via your project configuration:<\/p>\n<ItemGroup>\n <RuntimeHostConfigurationOption Include=\"System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault\" Value=\"true\" \/>\n<\/ItemGroup><\/code><\/pre>\nRespectNullableAnnotations<\/code> and RespectRequiredConstructorParameter<\/code> properties were implemented as opt-in flags to avoid breaking existing applications. If you’re writing a new application, it is highly recommended that you enable both flags in your code.<\/p>\nCustomizing enum member names<\/h2>\n
JsonStringEnumMemberName<\/code> attribute can be used to customize the names of individual enum members for types that are serialized as strings:<\/p>\nJsonSerializer.Serialize(MyEnum.Value1 | MyEnum.Value2); \/\/ \"Value1, Custom enum value\"\n\n[Flags, JsonConverter(typeof(JsonStringEnumConverter))]\nenum MyEnum\n{\n Value1 = 1,\n [JsonStringEnumMemberName(\"Custom enum value\")]\n Value2 = 2,\n}<\/code><\/pre>\nOut-of-order metadata reads<\/h2>\n
ReferenceHandler.Preserve<\/code> require emitting metadata properties over the wire:<\/p>\nJsonSerializerOptions options = new() { ReferenceHandler = ReferenceHandler.Preserve };\nBase value = new Derived(\"Name\");\nJsonSerializer.Serialize(value, options); \/\/ {\"$id\":\"1\",\"$type\":\"derived\",\"Name\":\"Name\"}\n\n[JsonDerivedType(typeof(Derived), \"derived\")]\nrecord Base;\nrecord Derived(string Name) : Base;<\/code><\/pre>\n$id<\/code> and $type<\/code> must be defined at the start of the JSON object:<\/p>\nJsonSerializer.Deserialize<Base>(\"\"\"{\"Name\":\"Name\",\"$type\":\"derived\"}\"\"\");\n\/\/ JsonException: The metadata property is either not supported by the\n\/\/ type or is not the first property in the deserialized JSON object.<\/code><\/pre>\nAllowOutOfOrderMetadataProperties<\/code> can be configured to disable this restriction:<\/p>\nJsonSerializerOptions options = new() { AllowOutOfOrderMetadataProperties = true };\nJsonSerializer.Deserialize<Base>(\"\"\"{\"Name\":\"Name\",\"$type\":\"derived\"}\"\"\", options); \/\/ Success<\/code><\/pre>\n$type<\/code> property must be kept in the buffer for subsequent property binding.<\/p>\nCustomizing indentation<\/h2>\n
JsonWriterOptions<\/code> and JsonSerializerOptions<\/code> types now expose APIs for configuring indentation. The following example enables single-tab indentation:<\/p>\nJsonSerializerOptions options = new()\n{\n WriteIndented = true,\n IndentCharacter = '\\t',\n IndentSize = 1,\n};\n\nJsonSerializer.Serialize(new { Value = 42 }, options);<\/code><\/pre>\nJsonObject<\/code> property order manipulation<\/h2>\nJsonObject<\/code> type is part of the mutable DOM and is used to represent JSON objects. Even though the type is modelled as an IDictionary<string, JsonNode><\/code>, it does encapsulate an implicit property order that is not user-modifiable. The new release exposes additional APIs that effectively model the type as an ordered dictionary:<\/p>\npublic partial class JsonObject : IList<KeyValuePair<string, JsonNode?>>\n{\n public int IndexOf(string key);\n public void Insert(int index, string key, JsonNode? value);\n public void RemoveAt(int index);\n}<\/code><\/pre>\n\/\/ Adds or moves the $id property to the start of the object\nvar schema = (JsonObject)JsonSerializerOptions.Default.GetJsonSchemaAsNode(typeof(MyPoco));\nswitch (schema.IndexOf(\"$id\", out JsonNode? idValue))\n{\n case < 0: \/\/ $id property missing\n idValue = (JsonNode)\"https:\/\/example.com\/schema\";\n schema.Insert(0, \"$id\", idValue);\n break;\n\n case 0: \/\/ $id property already at the start of the object\n break; \n\n case int index: \/\/ $id exists but not at the start of the object\n schema.RemoveAt(index);\n schema.Insert(0, \"$id\", idValue);\n}<\/code><\/pre>\nDeepEquals<\/code> methods in JsonElement<\/code> and JsonNode<\/code><\/h2>\nJsonElement.DeepEquals<\/code> method extends deep equality comparison to JsonElement<\/code> instances, complementing the pre-existing JsonNode.DeepEquals<\/code> method. Additionally, both methods include refinements in their implementation, such as handling of equivalent JSON numeric representations:<\/p>\nJsonElement left = JsonDocument.Parse(\"10e-3\").RootElement;\nJsonElement right = JsonDocument.Parse(\"0.001\").RootElement;\nJsonElement.DeepEquals(left, right); \/\/ True<\/code><\/pre>\nJsonSerializerOptions.Web<\/code><\/h2>\nJsonSerializerOptions.Web<\/code> singleton can be used to quickly serialize values using JsonSerializerDefaults.Web<\/code> settings:<\/p>\nJsonSerializerOptions options = JsonSerializerOptions.Web; \/\/ used instead of new(JsonSerializerDefaults.Web);\nJsonSerializer.Serialize(new { Value = 42 }, options); \/\/ {\"value\":42}<\/code><\/pre>\nPerformance improvements<\/h2>\n
Closing<\/h2>\n