JsonHelper.Net

JsonHelper.Net provides typed, null-safe JSONPath querying for Newtonsoft.Json. Eliminate repetitive null checks and type validation when extracting values from JToken objects.

Features

• Typed selectors — Extract string, bool, int, float, DateTime, Guid, List<T>, or raw JToken directly.
• Two usage styles — Use JsonHelper.SelectString(json, path) as a static helper or jtoken.SelectString(path) as a fluent extension method.
• Nullable vs. throwing — Every type provides a nullable method (returns null on missing/wrong type) and an OrThrow variant (throws JsonHelperException for strict validation).
• Custom date parsing — SelectDate(path, format) parses date strings from arbitrary formats via DateTime.ParseExact.
• Type-safe JToken access — SelectOrThrow(path, JTokenType.Array) validates the JSON token type at runtime.
• Built on Newtonsoft.Json 13.0.4 — Targets .NET 7 with nullable reference type annotations.

Quick start

usingNewtonsoft.Json.Linq;usingNewtonsoftJsonHelper;varjson=JToken.Parse("""{ "name": "Alice", "age": 30, "active": true, "score": 98.5, "joined": "2024-01-15T00:00:00", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}""");// --- Nullable style (returns null on missing/null/wrong type) ---string?maybe=json.SelectString("$.name");// "Alice"int?age=json.SelectInt("$.age");// 30bool?admin=json.SelectBoolean("$.admin");// null (missing path)// --- Throwing style (throws JsonHelperException on failure) ---stringname=json.SelectStringOrThrow("$.name");// "Alice"floatscore=json.SelectFloatOrThrow("$.score");// 98.5Guidid=json.SelectGuidOrThrow("$.id");// GuidDateTimedt=json.SelectDateOrThrow("$.joined");// DateTime// --- Without JsonHelper.Net (verbose boilerplate) ---varnameToken=json.SelectToken("$.name");varnameValue=nameToken?.ToObject<string>();if(nameToken==null||nameValue==null)thrownewException("Expected 'name' token");

API Reference

All methods exist in two forms — static JsonHelper and fluent JToken extension methods:

Category	Static (JsonHelper)	Extension (JTokenExtensions)
String	SelectString(json, path) / SelectStringOrThrow(json, path)	SelectString(path) / SelectStringOrThrow(path)
Boolean	SelectBoolean(json, path) / SelectBooleanOrThrow(json, path)	SelectBoolean(path) / SelectBooleanOrThrow(path)
Integer	SelectInt(json, path) / SelectIntOrThrow(json, path)	SelectInt(path) / SelectIntOrThrow(path)
Float	SelectFloat(json, path) / SelectFloatOrThrow(json, path)	SelectFloat(path) / SelectFloatOrThrow(path)
DateTime	SelectDate(json, path) / SelectDateOrThrow(json, path)	SelectDate(path) / SelectDateOrThrow(path)
DateTime (format)	SelectDate(json, path, format) / SelectDateOrThrow(json, path, format)	SelectDate(path, format) / SelectDateOrThrow(path, format)
Guid	SelectGuid(json, path) / SelectGuidOrThrow(json, path)	SelectGuid(path) / SelectGuidOrThrow(path)
List<T>	SelectList\<T\>(json, path) / SelectListOrThrow\<T\>(json, path)	SelectList\<T\>(path) / SelectListOrThrow\<T\>(path)
JToken	Select(json, path, params JTokenType[]) / SelectOrThrow(json, path, params JTokenType[])	Select(path, params JTokenType[]) / SelectOrThrow(path, params JTokenType[])

• Nullable methods return T? and return null when the token is missing, null, or of the wrong type.
• OrThrow methods return T (non-nullable) and throw JsonHelperException when the token cannot be resolved.

Advanced usage

Date with custom format

varjson=JToken.Parse("""{"published": "12/25/2023"}""");// Parse a string using DateTime.ParseExactDateTimechristmas=json.SelectDateOrThrow("$.published","MM/dd/yyyy");

List of values

varjson=JToken.Parse("""{"ratings": [4.5, 3.8, 5.0, 2.1]}""");List<float>ratings=json.SelectListOrThrow<float>("$.ratings");

Raw JToken with type validation

varjson=JToken.Parse("""{"metadata": {"key": "value"}}""");// Validates the token is an object, returns the JTokenJTokenmeta=json.SelectOrThrow("$.metadata",JTokenType.Object);// Works with multiple acceptable typesJTokenfield=json.Select("$.metadata",JTokenType.Object,JTokenType.String);

Why JsonHelper.Net?

Without this library, extracting typed values from JToken requires manual null checks and type validation every time:

// Manual checks every timevartoken=json.SelectToken("$.some.path");string?value=null;if(token!=null&&token.Type==JTokenType.String)value=token.ToObject<string>();if(value==null)thrownewException("Expected string at $.some.path");

With JsonHelper.Net this becomes a single call:

stringvalue=json.SelectStringOrThrow("$.some.path");

The library handles:

• JSONPath resolution
• Null checks (SelectToken can return null)
• Type validation (checks the JTokenType before converting)
• Parsing conversions (Guid from string, DateTime from string with format)
• Clear exception messages on failure

Installation

Nuget page is here

Contribution

Pull requests are welcome! I will gladly review any feature suggestions and consider them for inclusion in the library.