Generating 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

Copy

public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
}

Generate a JSON Schema from a .NET type

Copy

JSchemaGenerator generator = new JSchemaGenerator();

JSchema schema = generator.Generate(typeof(Person));
//{
//  "type": "object",
//  "properties": {
//    "Name": {
//      "type": [ "string", "null" ]
//    },
//    "Age": { "type": "integer" }
//  },
//  "required": [ "Name", "Age" ]
//}

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

Copy

JSchemaGenerator generator = new JSchemaGenerator();

// change contract resolver so property names are camel case
generator.ContractResolver = new CamelCasePropertyNamesContractResolver();

JSchema schema = generator.Generate(typeof(Person));
//{
//  "type": "object",
//  "properties": {
//    "name": {
//      "type": [ "string", "null" ]
//    },
//    "age": { "type": "integer" }
//  },
//  "required": [ "name", "age" ]
//}

SchemaIdGenerationHandling is used to control whether types with no ID defined have one infered from their type name.

Generate a JSON Schema using SchemaIdGenerationHandling

Copy

JSchemaGenerator generator = new JSchemaGenerator();

// types with no defined ID have their type name as the ID
generator.SchemaIdGenerationHandling = SchemaIdGenerationHandling.TypeName;

JSchema schema = generator.Generate(typeof(Person));
//{
//  "id": "Person",
//  "type": "object",
//  "properties": {
//    "name": {
//      "type": [ "string", "null" ]
//    },
//    "age": { "type": "integer" }
//  },
//  "required": [ "name", "age" ]
//}

JSchemaGenerator Settings

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

SchemaIdGenerationHandling - Controls how schema IDs are generated.
SchemaPropertyOrderHandling - Controls the order of object's properties in generated schemas.
SchemaLocationHandling - Controls where generated sub-schemas are located.
SchemaReferenceHandling - Controls what types schema's can be generated as a reference.
DefaultRequired - Controls the default required state of object's properties.
GenerationProviders - A collection of JSchemaGenerationProvider instances.
ContractResolver - The contract resolver used when generating schemas.

Using Data Annotation attributes

JSchemaGenerator will look for .NET Data Annotation attributes.

.NET type with Data Annotations

Copy

public class Building
{
    [Required]
    [MaxLength(100)]
    public string Name { get; set; }

    [Required]
    [Phone]
    public string PhoneNumber { get; set; }

    [Required]
    [EnumDataType(typeof(BuildingZone))]
    public string Zone { get; set; }
}

public enum BuildingZone
{
    Residential,
    Commercial,
    Industrial
}

Schema generation with Data Annotations

Copy

JSchemaGenerator generator = new JSchemaGenerator();

JSchema schema = generator.Generate(typeof(Building));
//{
//  "type": "object",
//  "properties": {
//    "Name": {
//      "type": "string",
//      "maxLength": 100
//    },
//    "PhoneNumber": {
//      "type": "string",
//      "format": "phone"
//    },
//    "Zone": {
//      "type": "string",
//      "enum": [
//        "Residential",
//        "Commercial",
//        "Industrial"
//      ]
//    }
//  },
//  "required": [
//    "Name",
//    "PhoneNumber",
//    "Zone"
//  ]
//}

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

Copy

JSchemaGenerator generator = new JSchemaGenerator();

JSchema schema = generator.Generate(typeof(BuildingReport));
//{
//  "type": "object",
//  "properties": {
//    "Date": {
//      "type": "string"
//    },
//    "Zone": {
//      "type": "integer",
//      "enum": [ 0, 1, 2 ]
//    }
//  },
//  "required": [ "Date", "Zone" ]
//}

// change Zone enum to generate a string property
JSchemaGenerator stringEnumGenerator = new JSchemaGenerator();
stringEnumGenerator.GenerationProviders.Add(new StringEnumGenerationProvider());

JSchema stringEnumSchema = stringEnumGenerator.Generate(typeof(BuildingReport));
//{
//  "type": "object",
//  "properties": {
//    "Date": {
//      "type": "string"
//    },
//    "Zone": {
//      "type": "string",
//      "enum": [ "Residential", "Commercial", "Industrial" ]
//    }
//  },
//  "required": [ "Date", "Zone" ]
//}

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

Reference

JSchemaGenerator

SchemaIdGenerationHandling

JSchemaGenerationProvider