import ""


Package genschema provides a generator for the JSON schema controller. The schema controller responds to GET /schema requests with the API JSON Hyper-schema. This JSON schema can be used to generate API documentation, ruby and Go API clients. See the blog post ( describing how Heroku leverages the JSON Hyper-schema standard ( for more information.


Package files

doc.go generator.go json_schema.go options.go


const (
    // JSONArray represents a JSON array.
    JSONArray JSONType = "array"
    // JSONBoolean represents a JSON boolean.
    JSONBoolean = "boolean"
    // JSONInteger represents a JSON number without a fraction or exponent part.
    JSONInteger = "integer"
    // JSONNumber represents any JSON number. Number includes integer.
    JSONNumber = "number"
    // JSONNull represents the JSON null value.
    JSONNull = "null"
    // JSONObject represents a JSON object.
    JSONObject = "object"
    // JSONString represents a JSON string.
    JSONString = "string"
    // JSONFile is an extension used by Swagger to represent a file download.
    JSONFile = "file"
const SchemaRef = ""

SchemaRef is the JSON Hyper-schema standard href.


var (
    // Definitions contains the generated JSON schema definitions
    Definitions map[string]*JSONSchema

func Generate

func Generate() (files []string, err error)

Generate is the generator entry point called by the meta generator.

func GenerateMediaTypeDefinition

func GenerateMediaTypeDefinition(api *design.APIDefinition, mt *design.MediaTypeDefinition, view string)

GenerateMediaTypeDefinition produces the JSON schema corresponding to the given media type and given view.

func GenerateResourceDefinition

func GenerateResourceDefinition(api *design.APIDefinition, r *design.ResourceDefinition)

GenerateResourceDefinition produces the JSON schema corresponding to the given API resource. It stores the results in cachedSchema.

func GenerateTypeDefinition

func GenerateTypeDefinition(api *design.APIDefinition, ut *design.UserTypeDefinition)

GenerateTypeDefinition produces the JSON schema corresponding to the given type.

func MediaTypeRef

func MediaTypeRef(api *design.APIDefinition, mt *design.MediaTypeDefinition, view string) string

MediaTypeRef produces the JSON reference to the media type definition with the given view.

func TypeRef

func TypeRef(api *design.APIDefinition, ut *design.UserTypeDefinition) string

TypeRef produces the JSON reference to the type definition.

type Generator

type Generator struct {
    API    *design.APIDefinition // The API definition
    OutDir string                // Path to output directory
    // contains filtered or unexported fields

Generator is the application code generator.

func NewGenerator

func NewGenerator(options ...Option) *Generator

NewGenerator returns an initialized instance of a JavaScript Client Generator

func (*Generator) Cleanup

func (g *Generator) Cleanup()

Cleanup removes all the files generated by this generator during the last invokation of Generate.

func (*Generator) Generate

func (g *Generator) Generate() (_ []string, err error)

Generate produces the skeleton main.

type JSONLink struct {
    Title        string      `json:"title,omitempty"`
    Description  string      `json:"description,omitempty"`
    Rel          string      `json:"rel,omitempty"`
    Href         string      `json:"href,omitempty"`
    Method       string      `json:"method,omitempty"`
    Schema       *JSONSchema `json:"schema,omitempty"`
    TargetSchema *JSONSchema `json:"targetSchema,omitempty"`
    MediaType    string      `json:"mediaType,omitempty"`
    EncType      string      `json:"encType,omitempty"`

JSONLink represents a “link” field in a JSON hyper schema.

type JSONMedia

type JSONMedia struct {
    BinaryEncoding string `json:"binaryEncoding,omitempty"`
    Type           string `json:"type,omitempty"`

JSONMedia represents a “media” field in a JSON hyper schema.

type JSONSchema

type JSONSchema struct {
    Schema string `json:"$schema,omitempty"`
    // Core schema
    ID           string                 `json:"id,omitempty"`
    Title        string                 `json:"title,omitempty"`
    Type         JSONType               `json:"type,omitempty"`
    Items        *JSONSchema            `json:"items,omitempty"`
    Properties   map[string]*JSONSchema `json:"properties,omitempty"`
    Definitions  map[string]*JSONSchema `json:"definitions,omitempty"`
    Description  string                 `json:"description,omitempty"`
    DefaultValue interface{}            `json:"default,omitempty"`
    Example      interface{}            `json:"example,omitempty"`

    // Hyper schema
    Media     *JSONMedia  `json:"media,omitempty"`
    ReadOnly  bool        `json:"readOnly,omitempty"`
    PathStart string      `json:"pathStart,omitempty"`
    Links     []*JSONLink `json:"links,omitempty"`
    Ref       string      `json:"$ref,omitempty"`

    // Validation
    Enum                 []interface{} `json:"enum,omitempty"`
    Format               string        `json:"format,omitempty"`
    Pattern              string        `json:"pattern,omitempty"`
    Minimum              *float64      `json:"minimum,omitempty"`
    Maximum              *float64      `json:"maximum,omitempty"`
    MinLength            *int          `json:"minLength,omitempty"`
    MaxLength            *int          `json:"maxLength,omitempty"`
    MinItems             *int          `json:"minItems,omitempty"`
    MaxItems             *int          `json:"maxItems,omitempty"`
    Required             []string      `json:"required,omitempty"`
    AdditionalProperties bool          `json:"additionalProperties,omitempty"`

    // Union
    AnyOf []*JSONSchema `json:"anyOf,omitempty"`

JSONSchema represents an instance of a JSON schema. See

func APISchema

func APISchema(api *design.APIDefinition) *JSONSchema

APISchema produces the API JSON hyper schema.

func NewJSONSchema

func NewJSONSchema() *JSONSchema

NewJSONSchema instantiates a new JSON schema.

func TypeSchema

func TypeSchema(api *design.APIDefinition, t design.DataType) *JSONSchema

TypeSchema produces the JSON schema corresponding to the given data type.

func (*JSONSchema) Dup

func (s *JSONSchema) Dup() *JSONSchema

Dup creates a shallow clone of the given schema.

func (*JSONSchema) JSON

func (s *JSONSchema) JSON() ([]byte, error)

JSON serializes the schema into JSON. It makes sure the “$schema” standard field is set if needed prior to delegating to the standard JSON marshaler.

func (*JSONSchema) Merge

func (s *JSONSchema) Merge(other *JSONSchema)

Merge does a two level deep merge of other into s.

type JSONType

type JSONType string

JSONType is the JSON type enum.

type Option

type Option func(*Generator)

Option a generator option definition

func API

func API(API *design.APIDefinition) Option

API The API definition

func OutDir

func OutDir(outDir string) Option

OutDir Path to output directory

Generated by godoc2md