How to parse JSON into an object in C#

using System.Text.Json;

string json = """
    {
      "name": "Ada Lovelace",
      "age": 36,
      "email": "[email protected]",
      "languages": ["English", "French"]
    }
    """;

// JsonSerializerOptions.Web: camelCase names, case-insensitive matching (.NET 9+)
User? user = JsonSerializer.Deserialize<User>(json, JsonSerializerOptions.Web);

Console.WriteLine(user!.Name);
Console.WriteLine(user.Age + 1);
Console.WriteLine(string.Join(", ", user.Languages));

// Without options, matching is case-sensitive: "name" does not fill Name
User? strict = JsonSerializer.Deserialize<User>(json);
Console.WriteLine(strict!.Name is null);
Console.WriteLine(strict.Age);

// Keys the type doesn't declare are skipped; missing ones keep their default
var partial = JsonSerializer.Deserialize<User>("""{"name":"Linus","country":"FI"}""", JsonSerializerOptions.Web);
Console.WriteLine($"{partial!.Name}, {partial.Age}, {partial.Languages is null}");

// The JSON literal null deserializes to a null reference
Console.WriteLine(JsonSerializer.Deserialize<User>("null") is null);

record User(string Name, int Age, string[] Languages);

using System.Text.Json;
using System.Text.Json.Serialization;

string json = """
    {
      "order_id": 1042,
      "customer_name": "Grace Hopper",
      "status": "Shipped",
      "total": "19.99",
      "ship-to": "Arlington, VA"
    }
    """;

var options = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower,       // order_id -> OrderId (.NET 8+)
    NumberHandling = JsonNumberHandling.AllowReadingFromString,   // "19.99" -> decimal
    Converters = { new JsonStringEnumConverter() },               // "Shipped" -> Status.Shipped
};

Order order = JsonSerializer.Deserialize<Order>(json, options)!;

Console.WriteLine(order.OrderId);
Console.WriteLine(order.CustomerName);
Console.WriteLine(order.Status == Status.Shipped);
Console.WriteLine(order.Total * 2);
Console.WriteLine(order.ShipTo);

// Without the converter, an enum is read from its number only
try
{
    JsonSerializer.Deserialize<Order>("""{"Status":"Shipped"}""");
}
catch (JsonException e)
{
    Console.WriteLine(e.Message);
}
Console.WriteLine(JsonSerializer.Deserialize<Order>("""{"Status":2}""")!.Status);

class Order
{
    public int OrderId { get; set; }
    public string CustomerName { get; set; } = "";
    public Status Status { get; set; }
    public decimal Total { get; set; }

    // An explicit name wins over the naming policy
    [JsonPropertyName("ship-to")]
    public string? ShipTo { get; set; }
}

enum Status { Pending, Shipped, Delivered }

using System.Text.Json;

// A top-level JSON array: deserialize into List<T> or T[]
string usersJson = """[{"name":"Ada","id":1},{"name":"Linus","id":2}]""";
List<User> users = JsonSerializer.Deserialize<List<User>>(usersJson, JsonSerializerOptions.Web)!;
Console.WriteLine(users.Count);
Console.WriteLine(users[1].Name);

int[] ids = JsonSerializer.Deserialize<int[]>("[3, 1, 4]")!;
Console.WriteLine(ids.Sum());

// Nested objects and arrays: declare a type for each level
string repoJson = """
    {
      "name": "compiler",
      "owner": { "name": "Ada", "id": 1 },
      "tags": ["csharp", "dotnet"],
      "contributors": [
        { "name": "Linus", "id": 2 },
        { "name": "Grace", "id": 3 }
      ]
    }
    """;
Repo repo = JsonSerializer.Deserialize<Repo>(repoJson, JsonSerializerOptions.Web)!;
Console.WriteLine(repo.Owner.Name);
Console.WriteLine(string.Join(" ", repo.Tags));
Console.WriteLine(string.Join(", ", repo.Contributors.Select(c => $"{c.Name} #{c.Id}")));

// An object whose keys are data, not field names: Dictionary<string, T>
string stockJson = """{"apples": 12, "pears": 0, "plums": 7}""";
var stock = JsonSerializer.Deserialize<Dictionary<string, int>>(stockJson)!;
foreach (var (fruit, count) in stock.OrderBy(kv => kv.Key))
    Console.WriteLine($"{fruit}: {count}");

record User(string Name, int Id);
record Repo(string Name, User Owner, List<string> Tags, List<User> Contributors);

using System.Text.Json;
using System.Text.Json.Nodes;

string json = """
    {
      "id": 7,
      "user": { "name": "Ada", "roles": ["admin", "dev"] },
      "settings": { "theme": "dark" }
    }
    """;

// JsonNode.Parse: walk any shape with indexers, no class needed
JsonNode root = JsonNode.Parse(json)!;

int id = root["id"]!.GetValue<int>();
string name = (string)root["user"]!["name"]!;          // explicit casts work too
string firstRole = (string)root["user"]!["roles"]![0]!;
Console.WriteLine($"{id} {name} {firstRole}");

// A missing key is null, so ?. and ?? handle optional data
string? language = (string?)root["settings"]?["language"];
Console.WriteLine(language ?? "(not set)");

// Arrays and objects can be enumerated
foreach (JsonNode? role in root["user"]!["roles"]!.AsArray())
    Console.WriteLine($"role: {role}");
foreach (var (key, value) in root["settings"]!.AsObject())
    Console.WriteLine($"{key} = {value}");

// JsonNode is mutable: change it and write it back out
root["settings"]!["theme"] = "light";
root["user"]!["roles"]!.AsArray().Add("ops");
Console.WriteLine(root.ToJsonString());

// Wrong type: GetValue throws instead of converting
try
{
    root["user"]!["name"]!.GetValue<int>();
}
catch (InvalidOperationException e)
{
    Console.WriteLine($"{e.GetType().Name}: {e.Message}");
}

using System.Text.Json;

string json = """
    {
      "city": "Oslo",
      "readings": [
        { "hour": 9, "temp": 4.5 },
        { "hour": 12, "temp": 7.25 },
        { "hour": 15, "temp": null }
      ]
    }
    """;

// JsonDocument is read-only and pooled: dispose it (using) when done
using JsonDocument doc = JsonDocument.Parse(json);
JsonElement root = doc.RootElement;

Console.WriteLine(root.GetProperty("city").GetString());

foreach (JsonElement r in root.GetProperty("readings").EnumerateArray())
{
    JsonElement temp = r.GetProperty("temp");
    string text = temp.ValueKind == JsonValueKind.Number ? temp.GetDouble().ToString() : "no reading";
    Console.WriteLine($"{r.GetProperty("hour").GetInt32()}:00 {text}");
}

// TryGetProperty for optional keys; GetProperty throws when one is missing
Console.WriteLine(root.TryGetProperty("country", out JsonElement country) ? country.GetString() : "no country");
try
{
    root.GetProperty("country");
}
catch (KeyNotFoundException e)
{
    Console.WriteLine(e.GetType().Name);
}

// object and dynamic both come back as a JsonElement, not a property bag
dynamic d = JsonSerializer.Deserialize<dynamic>(json)!;
Console.WriteLine(d.GetType().Name);
try
{
    Console.WriteLine(d.city);
}
catch (Microsoft.CSharp.RuntimeBinder.RuntimeBinderException e)
{
    Console.WriteLine(e.Message);
}

#nullable enable   // on in new projects by default; this playground needs the directive
using System.Text.Json;
using System.Text.Json.Serialization;

string[] inputs =
[
    """{"name":"Ada","age":36}""",
    """{"name":"Ada","age":"thirty-six"}""",
    """{"name":"Ada","age":36""",
    """{"age":36}""",
    """{"name":null,"age":36}""",
    """{"name":"Ada","age":36,"admin":true}""",
];

var options = new JsonSerializerOptions(JsonSerializerOptions.Web)
{
    RespectNullableAnnotations = true,                            // null into string throws (.NET 9+)
    UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow, // unknown keys throw (.NET 8+)
};

foreach (string json in inputs)
{
    try
    {
        Person p = JsonSerializer.Deserialize<Person>(json, options)!;
        Console.WriteLine($"ok: {p.Name}, {p.Age}");
    }
    catch (JsonException e)
    {
        Console.WriteLine($"JsonException: {e.Message}");
    }
}

class Person
{
    public required string Name { get; init; }   // C# 11 required: the key must be present
    public int Age { get; init; }
}