README
¶
Go JSON Schema Reflection
This package can be used to generate JSON Schemas from Go types through reflection.
It supports arbitrarily complex types, including interface{}, maps, slices, etc.
And it also supports json-schema features such as minLength, maxLength, pattern, format and etc.
Example
The following Go type:
type TestUser struct {
ID int `json:"id"`
Name string `json:"name" jsonschema="title=the name,description=The name of a friend,example=joe,example=lucy,default=alex"`
Friends []int `json:"friends,omitempty" jsonschema_description:"The list of IDs, omitted when empty"`
Tags map[string]interface{} `json:"tags,omitempty"`
BirthDate time.Time `json:"birth_date,omitempty"`
}
Results in following JSON Schema:
jsonschema.Reflect(&TestUser{})
{
"$schema": "http://json-schema.org/draft-04/schema#",
"$ref": "#/definitions/TestUser",
"definitions": {
"TestUser": {
"type": "object",
"properties": {
"birth_date": {
"type": "string",
"format": "date-time"
},
"friends": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The list of IDs, omitted when empty"
},
"id": {
"type": "integer"
},
"name": {
"type": "string",
"title": "the name",
"description": "The name of a friend",
"default": "alex",
"examples": [
"joe",
"lucy"
]
},
"tags": {
"type": "object",
"patternProperties": {
".*": {
"type": "object",
"additionalProperties": true
}
}
}
},
"additionalProperties": false,
"required": ["id", "name"]
}
}
}
Configurable behaviour
The behaviour of the schema generator can be altered with parameters when a jsonschema.Reflector
instance is created.
ExpandedStruct
If set to true, makes the top level struct not to reference itself in the definitions. But type passed should be a struct type.
eg.
type GrandfatherType struct {
FamilyName string `json:"family_name" jsonschema:"required"`
}
type SomeBaseType struct {
SomeBaseProperty int `json:"some_base_property"`
// The jsonschema required tag is nonsensical for private and ignored properties.
// Their presence here tests that the fields *will not* be required in the output
// schema, even if they are tagged required.
somePrivateBaseProperty string `json:"i_am_private" jsonschema:"required"`
SomeIgnoredBaseProperty string `json:"-" jsonschema:"required"`
SomeSchemaIgnoredProperty string `jsonschema:"-,required"`
SomeUntaggedBaseProperty bool `jsonschema:"required"`
someUnexportedUntaggedBaseProperty bool
Grandfather GrandfatherType `json:"grand"`
}
will output:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"required": [
"some_base_property",
"grand",
"SomeUntaggedBaseProperty"
],
"properties": {
"SomeUntaggedBaseProperty": {
"type": "boolean"
},
"grand": {
"$schema": "http://json-schema.org/draft-04/schema#",
"$ref": "#/definitions/GrandfatherType"
},
"some_base_property": {
"type": "integer"
}
},
"type": "object",
"definitions": {
"GrandfatherType": {
"required": [
"family_name"
],
"properties": {
"family_name": {
"type": "string"
}
},
"additionalProperties": false,
"type": "object"
}
}
}
Documentation
¶
Overview ¶
Package jsonschema uses reflection to generate JSON Schemas from Go types [1].
If json tags are present on struct fields, they will be used to infer property names and if a property is required (omitempty is present).
[1] http://json-schema.org/latest/json-schema-validation.html
Index ¶
Constants ¶
This section is empty.
Variables ¶
View Source
var Version = "http://json-schema.org/draft-04/schema#"
Version is the JSON Schema version. If extending JSON Schema with custom values use a custom URI. RFC draft-wright-json-schema-00, section 6
Functions ¶
This section is empty.
Types ¶
type Definitions ¶
Definitions hold schema definitions. http://json-schema.org/latest/json-schema-validation.html#rfc.section.5.26 RFC draft-wright-json-schema-validation-00, section 5.26
type Reflector ¶
type Reflector struct {
// AllowAdditionalProperties will cause the Reflector to generate a schema
// with additionalProperties to 'true' for all struct types. This means
// the presence of additional keys in JSON objects will not cause validation
// to fail. Note said additional keys will simply be dropped when the
// validated JSON is unmarshaled.
AllowAdditionalProperties bool
// RequiredFromJSONSchemaTags will cause the Reflector to generate a schema
// that requires any key tagged with `jsonschema:required`, overriding the
// default of requiring any key *not* tagged with `json:,omitempty`.
RequiredFromJSONSchemaTags bool
// ExpandedStruct will cause the toplevel definitions of the schema not
// be referenced itself to a definition.
ExpandedStruct bool
// IgnoredTypes defines a slice of types that should be ignored in the schema,
// switching to just allowing additional properties instead.
IgnoredTypes []interface{}
}
A Reflector reflects values into a Schema.
type Schema ¶
type Schema struct {
*Type
Definitions Definitions `json:"definitions,omitempty"`
}
Schema is the root schema. RFC draft-wright-json-schema-00, section 4.5
func Reflect ¶
func Reflect(v interface{}) *Schema
Reflect reflects to Schema from a value using the default Reflector
func ReflectFromType ¶
ReflectFromType generates root schema using the default Reflector
type Type ¶
type Type struct {
// RFC draft-wright-json-schema-00
Version string `json:"$schema,omitempty"` // section 6.1
Ref string `json:"$ref,omitempty"` // section 7
// RFC draft-wright-json-schema-validation-00, section 5
MultipleOf int `json:"multipleOf,omitempty"` // section 5.1
Maximum int `json:"maximum,omitempty"` // section 5.2
ExclusiveMaximum bool `json:"exclusiveMaximum,omitempty"` // section 5.3
Minimum int `json:"minimum,omitempty"` // section 5.4
ExclusiveMinimum bool `json:"exclusiveMinimum,omitempty"` // section 5.5
MaxLength int `json:"maxLength,omitempty"` // section 5.6
MinLength int `json:"minLength,omitempty"` // section 5.7
Pattern string `json:"pattern,omitempty"` // section 5.8
AdditionalItems *Type `json:"additionalItems,omitempty"` // section 5.9
Items *Type `json:"items,omitempty"` // section 5.9
MaxItems int `json:"maxItems,omitempty"` // section 5.10
MinItems int `json:"minItems,omitempty"` // section 5.11
UniqueItems bool `json:"uniqueItems,omitempty"` // section 5.12
MaxProperties int `json:"maxProperties,omitempty"` // section 5.13
MinProperties int `json:"minProperties,omitempty"` // section 5.14
Required []string `json:"required,omitempty"` // section 5.15
Properties map[string]*Type `json:"properties,omitempty"` // section 5.16
PatternProperties map[string]*Type `json:"patternProperties,omitempty"` // section 5.17
AdditionalProperties json.RawMessage `json:"additionalProperties,omitempty"` // section 5.18
Dependencies map[string]*Type `json:"dependencies,omitempty"` // section 5.19
Enum []interface{} `json:"enum,omitempty"` // section 5.20
Type interface{} `json:"type,omitempty"` // section 5.21
AllOf []*Type `json:"allOf,omitempty"` // section 5.22
AnyOf []*Type `json:"anyOf,omitempty"` // section 5.23
OneOf []*Type `json:"oneOf,omitempty"` // section 5.24
Not *Type `json:"not,omitempty"` // section 5.25
Definitions Definitions `json:"definitions,omitempty"` // section 5.26
// RFC draft-wright-json-schema-validation-00, section 6, 7
Title string `json:"title,omitempty"` // section 6.1
Description string `json:"description,omitempty"` // section 6.1
Default interface{} `json:"default,omitempty"` // section 6.2
Format string `json:"format,omitempty"` // section 7
Examples []interface{} `json:"examples,omitempty"` // section 7.4
// RFC draft-wright-json-schema-hyperschema-00, section 4
Media *Type `json:"media,omitempty"` // section 4.3
BinaryEncoding string `json:"binaryEncoding,omitempty"` // section 4.3
}
Type represents a JSON Schema object type.
Source Files
Click to show internal directories.
Click to hide internal directories.