JsonEasyNavigation

This library provides a wrapper class around JsonElement (located in System.Text.Json) which allows to navigate through JSON DOM (domain object model) hierarchy using indexer-style syntax (as in collections and dictionaries) for properties and array alike. It also contains useful methods to get values without throwing exceptions.

---

	Description
UPDATED:	9/17/2024
FRAMEWORK:	netstandard2.0, netstandard2.1, net9.0
LANGUAGE:	[C#] preview
OUTPUT TYPE:	Library [API]
SUPPORTS:	[Visual Studio]
GFX SUBSYS:	[None]
TAGS:	[text.json json navigation indexer dictionary list collection DOM]
STATUS:
LICENSE:
VERSION:

---

Navigation

• Introduction
• Usage
• Features
• Installation
• License

---

Introduction

This library provides a wrapper class around Microsoft's .NET JsonElement JsonElement (located in System.Text.Json) which allows to navigate through JSON DOM (domain object model) hierarchy using indexer-style syntax (as in collections and dictionaries) for properties and array alike. It also contains useful methods to get values without throwing exceptions. Target frameworks are .NET 5 and NET Standard 2.0.

Usage

Here is an example:

{
    "Persons": [
        {
            "Id": 0,
            "Name": "John",
            "SecondName": "Wick",
            "NickName": "Baba Yaga"
        },
        {
            "Id": 1,
            "Name": "Wade",
            "SecondName": "Winston",
            "NickName": "Deadpool"
        }
    ]
}

Assume that we are using System.Text.Json so we can create JsonDocument:

var jsonDocument = JsonDocument.Parse(json);

Then we convert this JSON document to the JsonNavigationElement provided by JsonEasyNavigation library:

var nav = jsonDocument.ToNavigation();

JsonNavigationElement is a struct, a wrapper around JsonElement. This struct provides many useful methods to operate arrays, objects and getting values from the JsonElement inside.

Now we can easley navigate Domain Object Model using indexers in a sequential style:

var arrayItem = nav[0]; // first item in the array
var id = arrayItem["Id"].GetInt32OrDefault(); // 0
var nickName = arrayItem["NickName"].GetStringOrDefault(); // "Baba Yaga"

Notice the usage of GetXxxOrDefault methods, which provides a convenient way to get values from the JsonElement without throwing exceptions. There are a lot of other similar useful methods.

We also can check if the property exist:

if (nav[0]["Age"].Exist)
{
    // Do something if the Age property of the first object in array exist.
}

JsonNavigationElement does not throw exception if a property or array item does not exist. You can always check Exist property of an JsonNavigationElement to be sure that corresponding JsonElement was found.

It is also possible to map JsonNavigationElement into the object of the specific type (using JsonSerializer internally):

public class Person
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string SecondName { get; set; }
    public string NickName { get; set; } 
}

// ...

var person = nav[0].Map<Person>();

Features

Overall, the library provides following features:

• A wrapper around JsonElement encapsulating all behaviour regarding to the DOM traversal and navigation (JsonNavigationElement);
• The API is implemented in a no-throw manner - you can "get" properties that don't exist in the DOM and check their existence;
• Implementation of a IReadOnlyDictionary and IReadOnlyCollection;
• Methods for converting values to the specified types in a type-safe way (and also generic methods like TryGetValue<T>);
• Extensions for caching properties and persisting their order for faster and easier JSON navigation.

Installation

This library can be installed using NuGet found here. This library can be installed using GitHub found here.

License

This software is distributed under the Apache License 2.0. See LICENSE.txt.

All graphical assets are licensed under the Creative Commons Attribution 3.0 Unported License.