jsonschema

README

jsonschema

A Go package that parses JSON Schema documents and generates go types including validations

Features

• Parses schema documents based on https://tools.ietf.org/html/draft-handrews-json-schema-00
• Supports schema validation based on http://json-schema.org/latest/json-schema-validation.html
• Creates a schema lookup index based on JSON Pointers
• Generates source code for any supported language (currently only Go)
• No dependencies on external packages
• Test suite with shared schema fixtures
• Library and standalone compiler binary jsonschemac

GoDoc

Godoc is available from https://godoc.org/github.com/tfkhsr/jsonschema.

Install

To install as library run:

go get -u github.com/tfkhsr/jsonschema

To install the standalone compiler binary jsonschemac run:

go get -u github.com/tfkhsr/jsonschema/cmd/jsonschemac

Documentation

Overview

Package jsonschema parses JSON Schema documents. The resulting schema can be used to generate source code in any supported language.

The JSON Schema implementation is based on https://tools.ietf.org/html/draft-handrews-json-schema-00. The validation implementation is based on http://json-schema.org/latest/json-schema-validation.html.

Validations

required: http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.5.3

Generators

go: https://godoc.org/github.com/tfkhsr/jsonschema/golang

Parse a schema into a map of JSON pointers to Schemas (Index):

schema := []byte(`{
  "definitions": {
    "user": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
      },
      "required": ["id"]
    }
}`)
idx, err := Parse(schema)
if err != nil {
	panic(err)
}

// idx now contains:
// "#/definitions/user"      : *Schema{...}
// "#/definitions/user/id"   : *Schema{...}
// "#/definitions/user/name" : *Schema{...}

Index

• type Index
  • func Parse(b []byte) (*Index, error)
• type Schema
  • func (s *Schema) NewInstance(idx *Index) (interface{}, error)

Examples

• Parse
• Schema.NewInstance

Types

type Index

type Index map[string]*Schema

Maps JSON pointers to Schemas

func Parse

func Parse(b []byte) (*Index, error)

Parse converts a raw JSON schema document to an Index of Schemas

Example

Parse a schema into an Index of Schemas

schema := `
{
	"definitions": {
		"user": {
			"type": "object",
			"properties": {
				"id": {
					"type": "string"
				},
				"name": {
					"type": "string"
				},
				"roles": {
					"$ref": "#/definitions/roles"
				}
			}
		},
		"roles": {
			"type": "array",
			"items": {
				"$ref": "#/definitions/role"
			}
		},
		"role": {
			"type": "object",
			"properties": {
				"name": {
					"type": "string"
				}
			},
			"required": ["name"]
		}
	}
}
`

// parse into index
idx, err := Parse([]byte(schema))
if err != nil {
	panic(err)
}

// sort pointers by name
pointers := make([]string, 0)
for pointer, _ := range *idx {
	pointers = append(pointers, pointer)
}
sort.Strings(pointers)

// print pointer and Go friendly name
for _, pointer := range pointers {
	fmt.Printf("%s : %s\n", pointer, (*idx)[pointer].Name)
}

Output:

#/definitions/role : Role
#/definitions/role/properties/name : Name
#/definitions/roles : Roles
#/definitions/roles/items : Items
#/definitions/user : User
#/definitions/user/properties/id : ID
#/definitions/user/properties/name : Name
#/definitions/user/properties/roles : Roles

type Schema

type Schema struct {
	// Optional Title
	Title string `json:"title"`

	// Optional Description
	Description string `json:"description"`

	// JSON pointer as defined in https://tools.ietf.org/html/rfc6901
	Pointer string `json:"pointer"`

	// JSON pointer without #/definitions/ part
	PointerName string

	// Camel-cased name
	Name string `json:"name"`

	// JSON friendly name
	JSONName string `json:"jsonName"`

	// Type as defined in http://json-schema.org/latest/json-schema-core.html#rfc.section.4.2
	Type string `json:"type"`

	// Definitions as defined in http://json-schema.org/latest/json-schema-validation.html#rfc.section.7.1
	Definitions Index `json:"definitions"`

	// Properties as defined in http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.18
	Properties Index `json:"properties"`

	// Items as defined in http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.9
	Items *Schema `json:"items"`

	// Reference as defined in http://json-schema.org/latest/json-schema-core.html#rfc.section.8
	Ref string `json:"$ref"`

	// Validation properties
	Required []string `json:"required"`
}

A schema is a part of a schema document tree

func (*Schema) NewInstance

func (s *Schema) NewInstance(idx *Index) (interface{}, error)

Creates a new instance conforming to the schema

Example

Generate a sample JSON document instance conforming to a schema

schema := `
{
	"definitions": {
		"user": {
			"type": "object",
			"properties": {
				"id": {
					"type": "string"
				},
				"name": {
					"type": "string"
				},
				"roles": {
					"$ref": "#/definitions/roles"
				}
			}
		},
		"roles": {
			"type": "array",
			"items": {
				"$ref": "#/definitions/role"
			}
		},
		"role": {
			"type": "object",
			"properties": {
				"name": {
					"type": "string"
				}
			},
			"required": ["name"]
		}
	}
}
`

// parse into index
idx, err := Parse([]byte(schema))
if err != nil {
	panic(err)
}

// create go instance
inst, err := (*idx)["#/definitions/user"].NewInstance(idx)
if err != nil {
	panic(err)
}

// marshal to json
raw, err := json.MarshalIndent(inst, "", "  ")
if err != nil {
	panic(err)
}

fmt.Printf("%s\n", raw)

Output:

{
  "id": "string",
  "name": "string",
  "roles": [
    {
      "name": "string"
    }
  ]
}