Getting Started
This guide will walk you through the essential steps to quickly get up and running with the JSchema library. It is also assumed a modest familiarity with the C# language, .NET SDK, and .NET CLI (command-line interface), including basic familiarity with NuGet packages.
NuGet Library Package
To get started, launch your preferred IDE (such as Visual Studio, JetBrains Rider, or VS Code) and open the C# project where you intend to include this library package. Within your IDE, navigate to the NuGet package manager and search for the package by the name RelogicLabs.JSchema. Subsequently, proceed to add or install the package to your project. Alternatively, you can use the .NET CLI to add the package to your project. Simply run the following command, replacing 2.x.x with either the latest version or your preferred version:
dotnet add package RelogicLabs.JSchema --version 2.x.x
To verify the successful integration of the library into your project, you may manually inspect your project file, typically named .csproj, using a text editor, and search for the following XML snippet within the file:
<ItemGroup>
<PackageReference Include="RelogicLabs.JSchema" Version="2.x.x" />
</ItemGroup>
For additional information regarding this library package, you can visit the NuGet package repository page of this library here.
Write a Sample to Test
With all the necessary components in place, you are now ready to create a sample schema and validate a corresponding JSON against the schema. The subsequent example presents a C# class featuring a method designed for validating a sample JSON based on a provided schema. If you are working with C# 10 or above, you can enhance the code further by utilizing new language features like raw string literals, file scoped namespaces and others.
using RelogicLabs.JSchema;
namespace CSharpApplication
{
public class SampleSchema
{
public bool CheckIsValid()
{
var schema =
@"%title: ""User Profile Response""
%version: ""1.0.0-basic""
%schema:
{
""user"": {
""id"": @range(1, 10000) #integer,
/*username does not allow special characters*/
""username"": @regex(""[a-z_]{3,30}"") #string,
/*currently only one role is allowed by system*/
""role"": ""user"" #string,
""isActive"": #boolean, //user account current status
""registeredAt"": #time,
""profile"": {
""firstName"": @regex(""[A-Za-z ]{3,50}"") #string,
""lastName"": @regex(""[A-Za-z ]{3,50}"") #string,
""dateOfBirth"": #date,
""age"": @range(18, 130) #integer,
""email"": @email #string,
""pictureURL"": @url #string,
""address"": {
""street"": @length(10, 200) #string,
""city"": @length(3, 50) #string,
""country"": @regex(""[A-Za-z ]{3,50}"") #string
} #object #null
}
}
}";
var json =
@"{
""user"": {
""id"": 9999,
""username"": ""johndoe"",
""role"": ""user"",
""isActive"": true,
""registeredAt"": ""2023-09-06T15:10:30.639Z"",
""profile"": {
""firstName"": ""John"",
""lastName"": ""Doe"",
""dateOfBirth"": ""1993-06-17"",
""age"": 30,
""email"": ""john.doe@example.com"",
""pictureURL"": ""https://example.com/picture.jpg"",
""address"": {
""street"": ""123 Some St"",
""city"": ""Some town"",
""country"": ""Some Country""
}
}
}
}";
JsonSchema jsonSchema = new(schema);
return jsonSchema.IsValid(json);
}
}
}
Create Validation Errors
Let's intentionally introduce a few errors by modifying the previous JSON document and then examine the validation results. To begin, we'll alter the id within the user object to a string type and observe the outcome. Additionally, we'll modify the username by inserting a space into its value, thus creating an invalid username. Below is the revised JSON representation, now containing these purposeful errors.
{
"user": {
"id": "not number",
"username": "john doe",
"role": "user",
"isActive": true,
"profile": {
"firstName": "John",
"lastName": "Doe",
"age": 30,
"email": "john.doe@example.com",
"pictureURL": "https://example.com/picture.jpg",
"address": {
"street": "123 Some St",
"city": "Some town",
"country": "Some Country"
}
}
}
}
To achieve the desired outcome, please make the following changes to the preceding code. Specifically, ensure that any schema validation errors are displayed in the console. The modified code snippet that invokes the WriteError method to display the errors if validation fails is as follows:
...
JsonSchema jsonSchema = new(schema);
if(!jsonSchema.IsValid(json)) jsonSchema.WriteError();
...
Here is the error as displayed in the console. More specific errors will be listed first, followed by more general errors. Consequently, the specific errors will precisely pinpoint the issues within the JSON document, while the generic errors will provide contextual information about where the errors occurred.
Schema (Line: 6:47) Json (Line: 3:30) [DTYP04]: Data type mismatch. Data type #integer is expected but found #string inferred by "not number".
Schema (Line: 6:30) Json (Line: 3:30) [FUNC03]: Function @range(1, 10000) is incompatible with the target data type. Applying to a supported data type such as #number is expected but applied to an unsupported data type #string of "not number".
Schema (Line: 8:36) Json (Line: 4:36) [REGX01]: Regex pattern does not match. String of pattern "[a-z_]{3,30}" is expected but found "john doe" that mismatches with pattern.
Schema (Line: 5:28) Json (Line: 2:28) [VALD01]: Validation failed. A valid value of {"id": @range(1, 10000) #integer, "username": @regex("[a-z_]{3,30}") #string, "role": "user" #string, "isActive": #boolean, "register...ing, "country": @regex("[A-Za-z ]{3,50}") #string} #object #null}} is expected but found {"id": "not number", "username": "john doe", "role": "user", "isActive": true, "registeredAt": "2023-09-06T15:10:30.639Z", "profile":...: "123 Some St", "city": "Some town", "country": "Some Country"}}}.
Schema (Line: 4:16) Json (Line: 1:0) [VALD01]: Validation failed. A valid value of {"user": {"id": @range(1, 10000) #integer, "username": @regex("[a-z_]{3,30}") #string, "role": "user" #string, "isActive": #boolean, ...ng, "country": @regex("[A-Za-z ]{3,50}") #string} #object #null}}} is expected but found {"user": {"id": "not number", "username": "john doe", "role": "user", "isActive": true, "registeredAt": "2023-09-06T15:10:30.639Z", "... "123 Some St", "city": "Some town", "country": "Some Country"}}}}.
Assertion for Validation
To utilize this library for test automation and API testing, you can use the following alternative code snippet to perform assertions on input JSON against a specified schema. For instance, let's examine how to assert the JSON, which has been intentionally altered to introduce some errors, against the aforementioned schema. The following demonstrates the adjusted code for asserting the JSON with errors:
...
try {
JsonAssert.IsValid(schema, json);
} catch(Exception e) {
Console.Error.WriteLine(e);
}
...
The following presents the printed stack trace for the preceding example. It's important to note that when using JsonAssert, it throws an exception upon encountering the first error, thus preventing the continuation of processing the rest of the schema:
RelogicLabs.JSchema.Exceptions.JsonSchemaException: DTYP04: Data type mismatch
Expected (Schema Line: 6:47): data type #integer
Actual (Json Line: 3:30): found #string inferred by "not number"
at RelogicLabs.JSchema.Nodes.JDataType.Match(JNode node)
at RelogicLabs.JSchema.Nodes.JValidator.CheckDataType(JNode node)
at RelogicLabs.JSchema.Nodes.JValidator.MatchDataType(JNode node)
at RelogicLabs.JSchema.Nodes.JValidator.Match(JNode node)
at RelogicLabs.JSchema.Nodes.JObject.Match(JNode node)
at RelogicLabs.JSchema.Nodes.JValidator.Match(JNode node)
at RelogicLabs.JSchema.Nodes.JObject.Match(JNode node)
at RelogicLabs.JSchema.Nodes.JValidator.Match(JNode node)
at RelogicLabs.JSchema.Nodes.JRoot.Match(JNode node)
at RelogicLabs.JSchema.Tree.SchemaTree.Match(IDataTree dataTree)
at RelogicLabs.JSchema.JsonAssert.IsValid(String json)
at RelogicLabs.JSchema.JsonAssert.IsValid(String schema, String json)
at CSharpApplication.SampleSchema.CheckIsValid() in /SampleSchema.cs:line 63
Similar to the above illustration, there are a lot of test cases with various types of examples available in the source code repository here.