README.md
1# Go JSON Schema Reflection
2
3[![Build Status](https://travis-ci.org/alecthomas/jsonschema.png)](https://travis-ci.org/alecthomas/jsonschema)
4[![Gitter chat](https://badges.gitter.im/alecthomas.png)](https://gitter.im/alecthomas/Lobby)
5[![Go Report Card](https://goreportcard.com/badge/github.com/alecthomas/jsonschema)](https://goreportcard.com/report/github.com/alecthomas/jsonschema)
6[![GoDoc](https://godoc.org/github.com/alecthomas/jsonschema?status.svg)](https://godoc.org/github.com/alecthomas/jsonschema)
7
8This package can be used to generate [JSON Schemas](http://json-schema.org/latest/json-schema-validation.html) from Go types through reflection.
9
10- Supports arbitrarily complex types, including `interface{}`, maps, slices, etc.
11- Supports json-schema features such as minLength, maxLength, pattern, format, etc.
12- Supports simple string and numeric enums.
13- Supports custom property fields via the `jsonschema_extras` struct tag.
14
15## Example
16
17The following Go type:
18
19```go
20type TestUser struct {
21 ID int `json:"id"`
22 Name string `json:"name" jsonschema:"title=the name,description=The name of a friend,example=joe,example=lucy,default=alex"`
23 Friends []int `json:"friends,omitempty" jsonschema_description:"The list of IDs, omitted when empty"`
24 Tags map[string]interface{} `json:"tags,omitempty" jsonschema_extras:"a=b,foo=bar,foo=bar1"`
25 BirthDate time.Time `json:"birth_date,omitempty" jsonschema:"oneof_required=date"`
26 YearOfBirth string `json:"year_of_birth,omitempty" jsonschema:"oneof_required=year"`
27 Metadata interface{} `json:"metadata,omitempty" jsonschema:"oneof_type=string;array"`
28 FavColor string `json:"fav_color,omitempty" jsonschema:"enum=red,enum=green,enum=blue"`
29}
30```
31
32Results in following JSON Schema:
33
34```go
35jsonschema.Reflect(&TestUser{})
36```
37
38```json
39{
40 "$schema": "http://json-schema.org/draft-04/schema#",
41 "$ref": "#/definitions/TestUser",
42 "definitions": {
43 "TestUser": {
44 "type": "object",
45 "properties": {
46 "metadata": {
47 "oneOf": [
48 {
49 "type": "string"
50 },
51 {
52 "type": "array"
53 }
54 ]
55 },
56 "birth_date": {
57 "type": "string",
58 "format": "date-time"
59 },
60 "friends": {
61 "type": "array",
62 "items": {
63 "type": "integer"
64 },
65 "description": "The list of IDs, omitted when empty"
66 },
67 "id": {
68 "type": "integer"
69 },
70 "name": {
71 "type": "string",
72 "title": "the name",
73 "description": "The name of a friend",
74 "default": "alex",
75 "examples": [
76 "joe",
77 "lucy"
78 ]
79 },
80 "tags": {
81 "type": "object",
82 "patternProperties": {
83 ".*": {
84 "additionalProperties": true
85 }
86 },
87 "a": "b",
88 "foo": [
89 "bar",
90 "bar1"
91 ]
92 },
93 "fav_color": {
94 "type": "string",
95 "enum": [
96 "red",
97 "green",
98 "blue"
99 ]
100 }
101 },
102 "additionalProperties": false,
103 "required": ["id", "name"],
104 "oneOf": [
105 {
106 "required": [
107 "birth_date"
108 ],
109 "title": "date"
110 },
111 {
112 "required": [
113 "year_of_birth"
114 ],
115 "title": "year"
116 }
117 ]
118 }
119 }
120}
121```
122## Configurable behaviour
123
124The behaviour of the schema generator can be altered with parameters when a `jsonschema.Reflector`
125instance is created.
126
127### ExpandedStruct
128
129If set to ```true```, makes the top level struct not to reference itself in the definitions. But type passed should be a struct type.
130
131eg.
132
133```go
134type GrandfatherType struct {
135 FamilyName string `json:"family_name" jsonschema:"required"`
136}
137
138type SomeBaseType struct {
139 SomeBaseProperty int `json:"some_base_property"`
140 // The jsonschema required tag is nonsensical for private and ignored properties.
141 // Their presence here tests that the fields *will not* be required in the output
142 // schema, even if they are tagged required.
143 somePrivateBaseProperty string `json:"i_am_private" jsonschema:"required"`
144 SomeIgnoredBaseProperty string `json:"-" jsonschema:"required"`
145 SomeSchemaIgnoredProperty string `jsonschema:"-,required"`
146 SomeUntaggedBaseProperty bool `jsonschema:"required"`
147 someUnexportedUntaggedBaseProperty bool
148 Grandfather GrandfatherType `json:"grand"`
149}
150```
151
152will output:
153
154```json
155{
156 "$schema": "http://json-schema.org/draft-04/schema#",
157 "required": [
158 "some_base_property",
159 "grand",
160 "SomeUntaggedBaseProperty"
161 ],
162 "properties": {
163 "SomeUntaggedBaseProperty": {
164 "type": "boolean"
165 },
166 "grand": {
167 "$schema": "http://json-schema.org/draft-04/schema#",
168 "$ref": "#/definitions/GrandfatherType"
169 },
170 "some_base_property": {
171 "type": "integer"
172 }
173 },
174 "type": "object",
175 "definitions": {
176 "GrandfatherType": {
177 "required": [
178 "family_name"
179 ],
180 "properties": {
181 "family_name": {
182 "type": "string"
183 }
184 },
185 "additionalProperties": false,
186 "type": "object"
187 }
188 }
189}
190```
191