Go JSON Schema Reflection

This package can be used to generate JSON Schemas from Go types through reflection.

• Supports arbitrarily complex types, including
  interface{}
  , maps, slices, etc.
• Supports json-schema features such as minLength, maxLength, pattern, format, etc.
• Supports simple string and numeric enums.
• Supports custom property fields via the
  jsonschema_extras
  struct tag.

This repository is a fork of the original jsonschema by @alecthomas. At Invopop we use jsonschema as a cornerstone in our GOBL library, and wanted to be able to continue building and adding features without taking up Alec's time. There have been a few significant changes that probably mean this version is a not compatible with with Alec's:

• The original was stuck on the draft-04 version of JSON Schema, we've now moved to the latest JSON Schema Draft 2020-12.
• Schema IDs are added automatically from the current Go package's URL in order to be unique, and can be disabled with the
  Anonymous
  option.
• Support for the
  FullyQualifyTypeName
  option has been removed. If you have conflicts, you should use multiple schema files with different IDs, set the
  DoNotReference
  option to true to hide definitions completely, or add your own naming strategy using the
  Namer
  property.

Example

The following Go type:

Results in following JSON Schema:

Configurable behaviour

The behaviour of the schema generator can be altered with parameters when a

instance is created.

ExpandedStruct

If set to

, makes the top level struct not to reference itself in the definitions. But type passed should be a struct type.

eg.

will output:

PreferYAMLSchema

JSON schemas can also be used to validate YAML, however YAML frequently uses different identifiers to JSON indicated by the

tag. The

Reflector

will by default prefer

json:

tags over

yaml:

tags (and only use the latter if the former are not present). This behavior can be changed via the

PreferYAMLSchema

flag, that will switch this behavior:

yaml:

tags will be preferred over

json:

tags.

With

, the following struct:

would result in this schema:

whereas without the flag one obtains:

Using Go Comments

Writing a good schema with descriptions inside tags can become cumbersome and tedious, especially if you already have some Go comments around your types and field definitions. If you'd like to take advantage of these existing comments, you can use the

method that forms part of the reflector to parse your go files and automatically generate a dictionary of Go import paths, types, and fields, to individual comments. These will then be used automatically as description fields, and can be overridden with a manual definition if needed.

Take a simplified example of a User struct which for the sake of simplicity we assume is defined inside this package:

To get the comments provided into your JSON schema, use a regular

and add the go code using an import module URL and path. Fully qualified go module paths cannot be determined reliably by the

go/parser

library, so we need to introduce this manually:

Expect the results to be similar to:

Custom Key Naming

In some situations, the keys actually used to write files are different from Go structs'.

This is often the case when writing a configuration file to YAML or JSON from a Go struct, or when returning a JSON response for a Web API: APIs typically use snake_case, while Go uses PascalCase.

You can pass a

function to

Reflector

's

KeyNamer

option to map Go field names to JSON key names and reflect the aforementionned transformations, without having to specify

json:"..."

on every struct field.

For example, consider the following struct

We can transform field names to snake_case in the generated JSON schema:

Will yield

As you can see, if a field name has a

or

yaml:""

tag set, the

key

argument to

KeyNamer

will have the value of that tag (if a field name has both, the value of

key

will respect

PreferYAMLSchema

).

Custom Type Definitions

Sometimes it can be useful to have custom JSON Marshal and Unmarshal methods in your structs that automatically convert for example a string into an object.

To override auto-generating an object type for your type, implement the

method and whatever is defined will be provided in the schema definitions.

Take the following simplified example of a

that only includes the Year and Month:

The resulting schema generated for this struct would look like: