swaggest / jsonschema-go

JSON Schema mapping for Go

JSON Schema structures for Go

This library provides Go structures to marshal/unmarshal and reflect JSON Schema documents.

Reflector

Documentation.

type MyStruct struct {
    Amount float64  `json:"amount" minimum:"10.5" example:"20.6" required:"true"`
    Abc    string   `json:"abc" pattern:"[abc]"`
    _      struct{} `additionalProperties:"false"`                   // Tags of unnamed field are applied to parent schema.
    _      struct{} `title:"My Struct" description:"Holds my data."` // Multiple unnamed fields can be used.
}

reflector := jsonschema.Reflector{}

schema, err := reflector.Reflect(MyStruct{})
if err != nil {
    log.Fatal(err)
}

j, err := json.MarshalIndent(schema, "", " ")
if err != nil {
    log.Fatal(err)
}

fmt.Println(string(j))

// Output:
// {
//  "title": "My Struct",
//  "description": "Holds my data.",
//  "required": [
//   "amount"
//  ],
//  "additionalProperties": false,
//  "properties": {
//   "abc": {
//    "pattern": "[abc]",
//    "type": "string"
//   },
//   "amount": {
//    "examples": [
//     20.6
//    ],
//    "minimum": 10.5,
//    "type": "number"
//   }
//  },
//  "type": "object"
// }

Customization

By default, JSON Schema is generated from Go struct field types and tags. It works well for the majority of cases, but if it does not there are rich customization options.

Field tags

type MyObj struct {
   BoundedNumber int `query:"boundedNumber" minimum:"-100" maximum:"100"`
   SpecialString string `json:"specialString" pattern:"^[a-z]{4}$" minLength:"4" maxLength:"4"`
}

Note: field tags are only applied to inline schemas, if you use named type then referenced schema will be created and tags will be ignored. This happens because referenced schema can be used in multiple fields with conflicting tags, therefore customization of referenced schema has to done on the type itself via RawExposer, Exposer or Preparer.

Each tag value has to be put in double quotes ("123").

These tags can be used:

• title, string
• description, string
• default, can be scalar or JSON value
• example, a scalar value that matches type of parent property, for an array it is applied to items
• examples, a JSON array value
• const, can be scalar or JSON value
• pattern, string
• format, string
• multipleOf, float > 0
• maximum, float
• minimum, float
• maxLength, integer
• minLength, integer
• maxItems, integer
• minItems, integer
• maxProperties, integer
• minProperties, integer
• exclusiveMaximum, boolean
• exclusiveMinimum, boolean
• uniqueItems, boolean
• enum, tag value must be a JSON or comma-separated list of strings
• required, boolean, marks property as required
• nullable, boolean, overrides nullability of the property

Unnamed fields can be used to configure parent schema:

type MyObj struct {
   BoundedNumber int `query:"boundedNumber" minimum:"-100" maximum:"100"`
   SpecialString string `json:"specialString" pattern:"^[a-z]{4}$" minLength:"4" maxLength:"4"`
   _             struct{} `additionalProperties:"false" description:"MyObj is my object."`
}

In case of a structure with multiple name tags, you can enable filtering of unnamed fields with ReflectContext.UnnamedFieldWithTag option and add matching name tags to structure (e.g. query:"_").

type MyObj struct {
   BoundedNumber int `query:"boundedNumber" minimum:"-100" maximum:"100"`
   SpecialString string `json:"specialString" pattern:"^[a-z]{4}$" minLength:"4" maxLength:"4"`
   // These parent schema tags would only be applied to `query` schema reflection (not for `json`).
   _ struct{} `query:"_" additionalProperties:"false" description:"MyObj is my object."`
}

Implementing interfaces on a type

There are a few interfaces that can be implemented on a type to customize JSON Schema generation.

• Preparer allows to change generated JSON Schema.
• Exposer overrides generated JSON Schema.
• RawExposer overrides generated JSON Schema.
• Described exposes description.
• Titled exposes title.
• Enum exposes enum values.
• NamedEnum exposes enum values with names.
• SchemaInliner inlines schema without creating a definition.
• IgnoreTypeName, when implemented on a mapped type forces the use of original type for definition name.
• EmbedReferencer, when implemented on an embedded field type, makes an allOf reference to that type definition.

And a few interfaces to expose subschemas (anyOf, allOf, oneOf, not and if, then, else).

• AnyOfExposer exposes anyOf subschemas.
• AllOfExposer exposes allOf subschemas.
• OneOfExposer exposes oneOf subschemas.
• NotExposer exposes not subschema.
• IfExposer exposes if subschema.
• ThenExposer exposes then subschema.
• ElseExposer exposes else subschema.

There are also helper functions jsonschema.AllOf, jsonschema.AnyOf, jsonschema.OneOf to create exposer instance from multiple values.

Configuring the reflector

Additional centralized configuration is available with jsonschema.ReflectContext and Reflect options.

• CollectDefinitions disables definitions storage in schema and calls user function instead.
• DefinitionsPrefix sets path prefix for definitions.
• PropertyNameTag allows using field tags other than json.
• InterceptSchema called for every type during schema reflection.
• InterceptProp called for every property during schema reflection.
• InlineRefs tries to inline all references (instead of creating definitions).
• RootNullable enables nullability of root schema.
• RootRef converts root schema to definition reference.
• StripDefinitionNamePrefix strips prefix from definition name.
• PropertyNameMapping explicit name mapping instead field tags.
• ProcessWithoutTags enables processing fields without any tags specified.

Virtual structure

Sometimes it is impossible to define a static Go struct, for example when fields are only known at runtime. Yet, you may need to include such fields in JSON schema reflection pipeline.

For any reflected value, standalone or nested, you can define a virtual structure that would be treated as a native Go struct.

s := jsonschema.Struct{}
s.SetTitle("Test title")
s.SetDescription("Test description")
s.DefName = "TestStruct"
s.Nullable = true

s.Fields = append(s.Fields, jsonschema.Field{
    Name:  "Foo",
    Value: "abc",
    Tag:   `json:"foo" minLength:"3"`,
})

r := jsonschema.Reflector{}
schema, _ := r.Reflect(s)
j, _ := assertjson.MarshalIndentCompact(schema, "", " ", 80)

fmt.Println("Standalone:", string(j))

type MyStruct struct {
    jsonschema.Struct // Can be embedded.

    Bar int `json:"bar"`

    Nested jsonschema.Struct `json:"nested"` // Can be nested.
}

ms := MyStruct{}
ms.Nested = s
ms.Struct = s

schema, _ = r.Reflect(ms)
j, _ = assertjson.MarshalIndentCompact(schema, "", " ", 80)

fmt.Println("Nested:", string(j))

// Output:
// Standalone: {
//  "title":"Test title","description":"Test description",
//  "properties":{"foo":{"minLength":3,"type":"string"}},"type":"object"
// }
// Nested: {
//  "definitions":{
//   "TestStruct":{
//    "title":"Test title","description":"Test description",
//    "properties":{"foo":{"minLength":3,"type":"string"}},"type":"object"
//   }
//  },
//  "properties":{
//   "bar":{"type":"integer"},"foo":{"minLength":3,"type":"string"},
//   "nested":{"$ref":"#/definitions/TestStruct"}
//  },
//  "type":"object"
// }

Custom Tags For Schema Definitions

If you're using additional libraries for validation, like for example go-playground/validator, you may want to infer validation rules into documented JSON schema.

type My struct {
    Foo *string `json:"foo" validate:"required"`
}

Normally, validate:"required" is not recognized, and you'd need to add required:"true" to have the rule exported to JSON schema.

However, it is possible to extend reflection with custom processing with InterceptProp option.

s, err := r.Reflect(My{}, jsonschema.InterceptProp(func(params jsonschema.InterceptPropParams) error {
    if !params.Processed {
        return nil
    }

    if v, ok := params.Field.Tag.Lookup("validate"); ok {
        if strings.Contains(v, "required") {
            params.ParentSchema.Required = append(params.ParentSchema.Required, params.Name)
        }
    }

    return nil
}))