README
¶
Maintenance of this project has moved to invopop/jsonschema.
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 ¶
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 ¶
func ExtractGoComments ¶
ExtractGoComments will read all the go files contained in the provided path, including sub-directories, in order to generate a dictionary of comments associated with Types and Fields. The results will be added to the `commentsMap` provided in the parameters and expected to be used for Schema "description" fields.
The `go/parser` library is used to extract all the comments and unfortunately doesn't have a built-in way to determine the fully qualified name of a package. The `base` paremeter, the URL used to import that package, is thus required to be able to match reflected types.
When parsing type comments, we use the `go/doc`'s Synopsis method to extract the first phrase only. Field comments, which tend to be much shorter, will include everything.
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
// YAMLEmbeddedStructs will cause the Reflector to generate a schema that does
// not inline embedded structs. This should be enabled if the JSON schemas are
// used with yaml.Marshal/Unmarshal.
YAMLEmbeddedStructs bool
// Prefer yaml: tags over json: tags to generate the schema even if json: tags
// are present
PreferYAMLSchema bool
// ExpandedStruct will cause the toplevel definitions of the schema not
// be referenced itself to a definition.
ExpandedStruct bool
// Do not reference definitions.
// All types are still registered under the "definitions" top-level object,
// but instead of $ref fields in containing types, the entire definition
// of the contained type is inserted.
// This will cause the entire structure of types to be output in one tree.
DoNotReference bool
// Use package paths as well as type names, to avoid conflicts.
// Without this setting, if two packages contain a type with the same name,
// and both are present in a schema, they will conflict and overwrite in
// the definition map and produce bad output. This is particularly
// noticeable when using DoNotReference.
FullyQualifyTypeNames bool
// IgnoredTypes defines a slice of types that should be ignored in the schema,
// switching to just allowing additional properties instead.
IgnoredTypes []interface{}
// TypeMapper is a function that can be used to map custom Go types to jsonschema types.
TypeMapper func(reflect.Type) *Type
// TypeNamer allows customizing of type names
TypeNamer func(reflect.Type) string
// AdditionalFields allows adding structfields for a given type
AdditionalFields func(reflect.Type) []reflect.StructField
// CommentMap is a dictionary of fully qualified go types and fields to comment
// strings that will be used if a description has not already been provided in
// the tags. Types and fields are added to the package path using "." as a
// separator.
//
// Type descriptions should be defined like:
//
// map[string]string{"github.com/alecthomas/jsonschema.Reflector": "A Reflector reflects values into a Schema."}
//
// And Fields defined as:
//
// map[string]string{"github.com/alecthomas/jsonschema.Reflector.DoNotReference": "Do not reference definitions."}
//
// See also: AddGoComments
CommentMap map[string]string
}
A Reflector reflects values into a Schema.
func (*Reflector) AddGoComments ¶
AddGoComments will update the reflectors comment map with all the comments found in the provided source directories. See the #ExtractGoComments method for more details.
type Schema ¶
type Schema struct {
*Type
Definitions Definitions
}
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
func (*Schema) MarshalJSON ¶
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 *orderedmap.OrderedMap `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 string `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-handrews-json-schema-validation-02, section 9.4
ReadOnly bool `json:"readOnly,omitempty"`
WriteOnly bool `json:"writeOnly,omitempty"`
// 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
Extras map[string]interface{} `json:"-"`
}
Type represents a JSON Schema object type.
Source Files
Directories