Click or drag to resize
Json.NETGenerating Schemas
 

Json.NET Schema supports automatically generating JSON Schemas for .NET types using the JSchemaGenerator object. The generator has a number of options for customizing generated schemas.

Generate JSON Schemas from .NET types

Schema generation is performed by the JSchemaGenerator object. It maps .NET objects, collections, properties, and their attributes to their JSON Schema equivalent. A generated schema will successfully validate serialized JSON for that type.

.NET type
1public class Person
2{
3    public string Name { get; set; }
4    public int Age { get; set; }
5}
Generate a JSON Schema from a .NET type
 1JSchemaGenerator generator = new JSchemaGenerator();
 2
 3JSchema schema = generator.Generate(typeof(Person));
 4//{
 5//  "type": "object",
 6//  "properties": {
 7//    "Name": {
 8//      "type": [ "string", "null" ]
 9//    },
10//    "Age": { "type": "integer" }
11//  },
12//  "required": [ "Name", "Age" ]
13//}

JSchemaGenerator has a number of options to customize output. An IContractResolver will customize how the type's properties and collections are reflected.

Generate a JSON Schema using an IContractResolver
 1JSchemaGenerator generator = new JSchemaGenerator();
 2
 3// change contract resolver so property names are camel case
 4generator.ContractResolver = new CamelCasePropertyNamesContractResolver();
 5
 6JSchema schema = generator.Generate(typeof(Person));
 7//{
 8//  "type": "object",
 9//  "properties": {
10//    "name": {
11//      "type": [ "string", "null" ]
12//    },
13//    "age": { "type": "integer" }
14//  },
15//  "required": [ "name", "age" ]
16//}
SchemaIdGenerationHandling is used to control whether types with no ID defined have one infered from their type name.
Generate a JSON Schema using SchemaIdGenerationHandling
 1JSchemaGenerator generator = new JSchemaGenerator();
 2
 3// types with no defined ID have their type name as the ID
 4generator.SchemaIdGenerationHandling = SchemaIdGenerationHandling.TypeName;
 5
 6JSchema schema = generator.Generate(typeof(Person));
 7//{
 8//  "id": "Person",
 9//  "type": "object",
10//  "properties": {
11//    "name": {
12//      "type": [ "string", "null" ]
13//    },
14//    "age": { "type": "integer" }
15//  },
16//  "required": [ "name", "age" ]
17//}
JSchemaGenerator Settings

There are many settings on JSchemaGenerator for controlling how schemas are generated from your .NET types.

Using Data Annotation attributes

JSchemaGenerator will look for .NET Data Annotation attributes.

.NET type with Data Annotations
 1public class Building
 2{
 3    [Required]
 4    [MaxLength(100)]
 5    public string Name { get; set; }
 6
 7    [Required]
 8    [Phone]
 9    public string PhoneNumber { get; set; }
10
11    [Required]
12    [EnumDataType(typeof(BuildingZone))]
13    public string Zone { get; set; }
14}
15
16public enum BuildingZone
17{
18    Residential,
19    Commercial,
20    Industrial
21}
Schema generation with Data Annotations
 1JSchemaGenerator generator = new JSchemaGenerator();
 2
 3JSchema schema = generator.Generate(typeof(Building));
 4//{
 5//  "type": "object",
 6//  "properties": {
 7//    "Name": {
 8//      "type": "string",
 9//      "maxLength": 100
10//    },
11//    "PhoneNumber": {
12//      "type": "string",
13//      "format": "phone"
14//    },
15//    "Zone": {
16//      "type": "string",
17//      "enum": [
18//        "Residential",
19//        "Commercial",
20//        "Industrial"
21//      ]
22//    }
23//  },
24//  "required": [
25//    "Name",
26//    "PhoneNumber",
27//    "Zone"
28//  ]
29//}

The following are the Data Annotation attributes used when generating a schema and their effects:

Data Annotation

Effect

RequiredAttribute

Property will be required.

MinLengthAttribute

minLength of a string or the minItems in an array.

MaxLengthAttribute

maxLength of a string or the maxItems in an array.

RegularExpressionAttribute

String pattern.

RangeAttribute

Number minimum and maximum.

StringLengthAttribute

String minLength and maxLength.

EnumDataTypeAttribute

Enum type used to generate enum values.

DataTypeAttribute

String format depending on the DataType value. Supports Url, Date, Time, DateTime, EmailAddress, PhoneNumber.

UrlAttribute

String uri format.

PhoneAttribute

String phone format.

EmailAddressAttribute

String email format.

Control Schema Generation with JSchemaGenerationProvider

JSchemaGenerationProvider lets you completely take over schema generation for a type. An example of where this is useful is changing the schema generation for Enum types from int enum values to string enum values.

Schema generation with JSchemaGenerationProvider
 1JSchemaGenerator generator = new JSchemaGenerator();
 2
 3JSchema schema = generator.Generate(typeof(BuildingReport));
 4//{
 5//  "type": "object",
 6//  "properties": {
 7//    "Date": {
 8//      "type": "string"
 9//    },
10//    "Zone": {
11//      "type": "integer",
12//      "enum": [ 0, 1, 2 ]
13//    }
14//  },
15//  "required": [ "Date", "Zone" ]
16//}
17
18// change Zone enum to generate a string property
19JSchemaGenerator stringEnumGenerator = new JSchemaGenerator();
20stringEnumGenerator.GenerationProviders.Add(new StringEnumGenerationProvider());
21
22JSchema stringEnumSchema = stringEnumGenerator.Generate(typeof(BuildingReport));
23//{
24//  "type": "object",
25//  "properties": {
26//    "Date": {
27//      "type": "string"
28//    },
29//    "Zone": {
30//      "type": "string",
31//      "enum": [ "Residential", "Commercial", "Industrial" ]
32//    }
33//  },
34//  "required": [ "Date", "Zone" ]
35//}

Json.NET Schema includes StringEnumGenerationProvider. Additional schema providers can be created by inheriting from JSchemaGenerationProvider

.
See Also