JSON Schema draft v4 reader, generator and validator for .NET
C# Batchfile
Switch branches/tags
v7.0 v6.0 NSwag-Build-1683 NSwag-Build-1682 NSwag-Build-1680 NSwag-Build-1679 NSwag-Build-1678 NSwag-Build-1677 NSwag-Build-1676 NSwag-Build-1675 NSwag-Build-1674 NSwag-Build-1673 NSwag-Build-1672 NSwag-Build-1671 NSwag-Build-1670 NSwag-Build-1669 NSwag-Build-1668 NSwag-Build-1667 NSwag-Build-1666 NSwag-Build-1665 NSwag-Build-1664 NSwag-Build-1663 NSwag-Build-1662 NSwag-Build-1661 NSwag-Build-1660 NSwag-Build-1659 NSwag-Build-1658 NSwag-Build-1657 NSwag-Build-1656 NSwag-Build-1655 NSwag-Build-1654 NSwag-Build-1653 NSwag-Build-1652 NSwag-Build-1651 NSwag-Build-1650 NSwag-Build-1649 NSwag-Build-1648 NSwag-Build-1647 NSwag-Build-1646 NSwag-Build-1645 NSwag-Build-1644 NSwag-Build-1643 NSwag-Build-1642 NSwag-Build-1641 NSwag-Build-1640 NSwag-Build-1639 NSwag-Build-1638 NSwag-Build-1637 NSwag-Build-1636 NSwag-Build-1635 NSwag-Build-1634 NSwag-Build-1633 NSwag-Build-1632 NSwag-Build-1631 NSwag-Build-1630 NSwag-Build-1629 NSwag-Build-1628 NSwag-Build-1627 NSwag-Build-1626 NSwag-Build-1625 NSwag-Build-1624 NSwag-Build-1623 NSwag-Build-1622 NSwag-Build-1621 NSwag-Build-1620 NSwag-Build-1619 NSwag-Build-1618 NSwag-Build-1617 NSwag-Build-1616 NSwag-Build-1615 NSwag-Build-1614 NSwag-Build-1613 NSwag-Build-1612 NSwag-Build-1611 NSwag-Build-1610 NSwag-Build-1609 NSwag-Build-1608 NSwag-Build-1607 NSwag-Build-1606 NSwag-Build-1605 NSwag-Build-1604 NSwag-Build-1603 NSwag-Build-1602 NSwag-Build-1601 NSwag-Build-1600 NSwag-Build-1599 NSwag-Build-1598 NSwag-Build-1597 NSwag-Build-1596 NSwag-Build-1595 NSwag-Build-1594 NSwag-Build-1593 NSwag-Build-1592 NSwag-Build-1591 NSwag-Build-1590 NSwag-Build-1589 NSwag-Build-1588 NSwag-Build-1587 NSwag-Build-1586 NSwag-Build-1585
Nothing to show
Latest commit 32e056f Sep 21, 2017 @RSuter Avoid NPE, closes #482

README.md

NJsonSchema for .NET

NuGet Version Build status Build status Gitter StackOverflow

NJsonSchema is a .NET library to read, generate and validate JSON Schema draft v4 schemas. The library can read a schema from a file or string and validate JSON data against it. A schema can also be generated from an existing .NET class. With the code generation APIs you can generate C# and TypeScript classes or interfaces from a schema.

The library uses Json.NET to read and write JSON data.

NuGet packages:

The NuGet packages may require the Microsoft.NETCore.Portable.Compatibility package on .NET Core/UWP targets (if mscorlib is missing).

CI NuGet Feed: https://www.myget.org/gallery/njsonschema-ci

Features:

  • Read existing JSON Schemas and validate JSON data (JsonSchema4.FromJsonAsync())
  • Generate JSON Schema from .NET type via reflection (with support for many attributes/annotations) (JsonSchema4.FromTypeAsync<MyType>())
  • Generate JSON Schema from sample JSON data (JsonSchema4.FromData())
  • Support for schema references ($ref) (relative, URL and file)
  • Generate C# and TypeScript code from JSON Schema
  • Support for .NET Core (via PCL 259 / .NET Standard 1.0, also see XML Documentation)

NJsonSchema is heavily used in NSwag, a Swagger API toolchain for .NET which generates client code for Web API services. NSwag also provides command line tools to use the NJsonSchema's JSON Schema generator (command types2swagger).

The project is developed and maintained by Rico Suter and other contributors.

NJsonSchema usage

The JsonSchema4 class can be used as follows:

var schema = await JsonSchema4.FromTypeAsync<Person>();
var schemaData = schema.ToJson();
var errors = schema.Validate("{...}");

foreach (var error in errors)
    Console.WriteLine(error.Path + ": " + error.Kind);

schema = await JsonSchema4.FromJsonAsync(schemaData);

The Person class:

public class Person
{
    [Required]
    public string FirstName { get; set; }

    public string MiddleName { get; set; }

    [Required]
    public string LastName { get; set; }

    public Gender Gender { get; set; }

    [Range(2, 5)]
    public int NumberWithRange { get; set; }

    public DateTime Birthday { get; set; }

    public Company Company { get; set; }

    public Collection<Car> Cars { get; set; }
}

public enum Gender
{
    Male,
    Female
}

public class Car
{
    public string Name { get; set; }

    public Company Manufacturer { get; set; }
}

public class Company
{
    public string Name { get; set; }
}

The generated JSON schema data stored in the schemaData variable:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Person",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "FirstName",
    "LastName"
  ],
  "properties": {
    "FirstName": {
      "type": "string"
    },
    "MiddleName": {
      "type": [
        "null",
        "string"
      ]
    },
    "LastName": {
      "type": "string"
    },
    "Gender": {
      "oneOf": [
        {
          "$ref": "#/definitions/Gender"
        }
      ]
    },
    "NumberWithRange": {
      "type": "integer",
      "format": "int32",
      "maximum": 5.0,
      "minimum": 2.0
    },
    "Birthday": {
      "type": "string",
      "format": "date-time"
    },
    "Company": {
      "oneOf": [
        {
          "$ref": "#/definitions/Company"
        },
        {
          "type": "null"
        }
      ]
    },
    "Cars": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/definitions/Car"
      }
    }
  },
  "definitions": {
    "Gender": {
      "type": "integer",
      "description": "",
      "x-enumNames": [
        "Male",
        "Female"
      ],
      "enum": [
        0,
        1
      ]
    },
    "Company": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "Name": {
          "type": [
            "null",
            "string"
          ]
        }
      }
    },
    "Car": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "Name": {
          "type": [
            "null",
            "string"
          ]
        },
        "Manufacturer": {
          "oneOf": [
            {
              "$ref": "#/definitions/Company"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    }
  }
}

NJsonSchema.CodeGeneration usage

The NJsonSchema.CodeGeneration can be used to generate C# or TypeScript code from a JSON schema:

var generator = new CSharpGenerator(schema);
var file = generator.GenerateFile();

The file variable now contains the C# code for all the classes defined in the JSON schema.

TypeScript

The previously generated JSON Schema would generate the following TypeScript interfaces.

Settings:

new TypeScriptGeneratorSettings { TypeStyle = TypeScriptTypeStyle.Interface, TypeScriptVersion = 2.0m }

Output:

export enum Gender {
    Male = 0, 
    Female = 1, 
}

export interface Company {
    Name: string | undefined;
}

export interface Car {
    Name: string | undefined;
    Manufacturer: Company | undefined;
}

export interface Person {
    FirstName: string;
    MiddleName: string | undefined;
    LastName: string;
    Gender: Gender;
    NumberWithRange: number;
    Birthday: Date;
    Company: Company | undefined;
    Cars: Car[] | undefined;
}

... and the following TypeScript classes.

Settings:

new TypeScriptGeneratorSettings { TypeStyle = TypeScriptTypeStyle.Class, TypeScriptVersion = 2.0m }

Output:

export enum Gender {
    Male = 0, 
    Female = 1, 
}

export class Company implements ICompany {
    name: string | undefined;

    constructor(data?: ICompany) {
        if (data) {
            for (var property in data) {
                if (data.hasOwnProperty(property))
                    (<any>this)[property] = (<any>data)[property];
            }
        }
    }

    init(data?: any) {
        if (data) {
            this.name = data["Name"];
        }
    }

    static fromJS(data: any): Company {
        let result = new Company();
        result.init(data);
        return result;
    }

    toJSON(data?: any) {
        data = typeof data === 'object' ? data : {};
        data["Name"] = this.name;
        return data; 
    }
}

export interface ICompany {
    name: string | undefined;
}

export class Car implements ICar {
    name: string | undefined;
    manufacturer: Company | undefined;

    constructor(data?: ICar) {
        if (data) {
            for (var property in data) {
                if (data.hasOwnProperty(property))
                    (<any>this)[property] = (<any>data)[property];
            }
        }
    }

    init(data?: any) {
        if (data) {
            this.name = data["Name"];
            this.manufacturer = data["Manufacturer"] ? Company.fromJS(data["Manufacturer"]) : <any>undefined;
        }
    }

    static fromJS(data: any): Car {
        let result = new Car();
        result.init(data);
        return result;
    }

    toJSON(data?: any) {
        data = typeof data === 'object' ? data : {};
        data["Name"] = this.name;
        data["Manufacturer"] = this.manufacturer ? this.manufacturer.toJSON() : <any>undefined;
        return data; 
    }
}

export interface ICar {
    name: string | undefined;
    manufacturer: Company | undefined;
}

export class Person implements IPerson {
    firstName: string;
    middleName: string | undefined;
    lastName: string;
    gender: Gender;
    numberWithRange: number;
    birthday: Date;
    company: Company | undefined;
    cars: Car[] | undefined;

    constructor(data?: IPerson) {
        if (data) {
            for (var property in data) {
                if (data.hasOwnProperty(property))
                    (<any>this)[property] = (<any>data)[property];
            }
        }
    }

    init(data?: any) {
        if (data) {
            this.firstName = data["FirstName"];
            this.middleName = data["MiddleName"];
            this.lastName = data["LastName"];
            this.gender = data["Gender"];
            this.numberWithRange = data["NumberWithRange"];
            this.birthday = data["Birthday"] ? new Date(data["Birthday"].toString()) : <any>undefined;
            this.company = data["Company"] ? Company.fromJS(data["Company"]) : <any>undefined;
            if (data["Cars"] && data["Cars"].constructor === Array) {
                this.cars = [];
                for (let item of data["Cars"])
                    this.cars.push(Car.fromJS(item));
            }
        }
    }

    static fromJS(data: any): Person {
        let result = new Person();
        result.init(data);
        return result;
    }

    toJSON(data?: any) {
        data = typeof data === 'object' ? data : {};
        data["FirstName"] = this.firstName;
        data["MiddleName"] = this.middleName;
        data["LastName"] = this.lastName;
        data["Gender"] = this.gender;
        data["NumberWithRange"] = this.numberWithRange;
        data["Birthday"] = this.birthday ? this.birthday.toISOString() : <any>undefined;
        data["Company"] = this.company ? this.company.toJSON() : <any>undefined;
        if (this.cars && this.cars.constructor === Array) {
            data["Cars"] = [];
            for (let item of this.cars)
                data["Cars"].push(item.toJSON());
        }
        return data; 
    }
}

export interface IPerson {
    firstName: string;
    middleName: string | undefined;
    lastName: string;
    gender: Gender;
    numberWithRange: number;
    birthday: Date;
    company: Company | undefined;
    cars: Car[] | undefined;
}

Final notes

Applications which use the library:

  • VisualJsonEditor, a JSON schema based file editor for Windows.
  • NSwag: The Swagger API toolchain for .NET