jsonschema

README

caddy-json-schema

JSON schema generator for Caddy v2.

The generated schema can be integrated with editors for intellisense and better experience with configuration and plugin development.

Installation

The generated schema is for the caddy binary. i.e. all modules in the binary will be include in the schema.

xcaddy build v2.0.0 \
    --with github.com/abiosoft/caddy-json-schema \
    # any other module you want to include in the generated schema

Usage

Run caddy help json-schema to view help.

usage:
  caddy json-schema [--output <file>] [--indent <int>] [--vscode] [--no-cache]

flags:
  -indent int
        Number of spaces to indent the generated JSON with (default 2)
  -no-cache
        Discard local cache and fetch latest API docs
  -output string
        The file to write the generated schema (default "./caddy_schema.json")
  -vscode
        Generate VSCode configuration

Editors

Visual Studio Code

caddy json-schema --vscode generates Visual Studio Code configuration in the current directory.

Open the directory in Visual Studio Code and it should just work. Ensure the config filename is of the format *caddy*.[json|yaml].

Note that you need vscode-yaml plugin to get similar experience for YAML files.

Vim/NeoVim

There are multiple Vim/NeoVim plugins with language server and JSON schema support.

Below is a config for coc-json and coc-yaml. The path to schema file is relative to the config file being edited.

{
    "json.schemas": [
        {
            "fileMatch": [
                "*caddy*.json"
            ],
            "url": "./caddy_schema.json"
        }
    ],
    "yaml.schemas": {
        ".vscode/caddy_schema.json": [
            "*caddy*.yaml",
            "*caddy*.yml"
        ]
    }
}

Features

Modules	Intellisense	Documentation
Standard	Supported	Supported
Third Party	Supported	Planned

License

Apache 2

Documentation

Index

• type DocAPIResp
• type DocNamespace
• type DocStruct
• type Interface
• type M
• type Module
• type Modules
• type Schema
  • func NewSchema() *Schema
  • func (s *Schema) MarshalJSON() ([]byte, error)

Types

type DocAPIResp

type DocAPIResp struct {
	Structure  *DocStruct   `json:"structure,omitempty"`
	Namespaces DocNamespace `json:"namespaces,omitempty"`
}

DocAPIResp is the API response for a namespace documentation request.

type DocNamespace

type DocNamespace map[string][]struct {
	Name string `json:"name,omitempty"`
	Docs string `json:"docs,omitempty"`

	Structure *DocStruct `json:"-"`
}

DocNamespace is the API response structure for namespaces

type DocStruct

type DocStruct struct {
	Type    string `json:"type,omitempty"`
	Package string `json:"type_name,omitempty"`
	Doc     string `json:"doc,omitempty"`

	Key     string     `json:"key,omitempty"`
	Value   *DocStruct `json:"value,omitempty"`
	Elems   *DocStruct `json:"elems,omitempty"`
	MapKeys struct {
		Type string `json:"type,omitempty"`
	} `json:"map_keys,omitempty"`

	Namespace string `json:"module_namespace,omitempty"`
	InlineKey string `json:"module_inline_key,omitempty"`

	StructFields []*DocStruct `json:"struct_fields,omitempty"`
}

DocStruct is the API response structure for a type.

type Interface

type Interface struct {
	// keep track of the current module
	Module string

	// properties
	Name     string
	Fields   []Interface
	Type     string
	Nullable bool

	// array/map type
	Array bool
	Map   bool // map key is always string
	Nest  *Interface

	// Module loaders
	Loader     []string // list of modules
	LoaderKey  string   // inline_key
	LoaderType reflect.Type
}

Interface is a Go type representing a Caddy module structure or property.

type M

type M map[string]interface{}

M is a convenience wrapper for JSON object.

type Module

type Module struct {
	Name      string
	Type      interface{}
	Interface Interface
}

Module is a basic information about a Caddy module.

type Modules

type Modules map[string]Module

Modules is list of Module. Map is used for quicker access and ease of fetching module name.

type Schema

type Schema struct {
	Title               string `json:"title,omitempty"`
	Description         string `json:"description,omitempty"`
	MarkdownDescription string `json:"markdownDescription,omitempty"`
	Type                string `json:"type,omitempty"`
	Nullable            bool   `json:"-"`
	Ref                 string `json:"$ref,omitempty"`

	ArrayItems           *Schema            `json:"items,omitempty"`
	Definitions          map[string]*Schema `json:"definitions,omitempty"`
	Properties           map[string]*Schema `json:"properties,omitempty"`
	AdditionalProperties *Schema            `json:"additionalProperties,omitempty"`
	Required             []string           `json:"required,omitempty"`
	Enum                 []string           `json:"enum,omitempty"`

	AdditionalItems bool      `json:"additionalItems,omitempty"`
	AllOf           []*Schema `json:"allOf,omitempty"`
	AnyOf           []*Schema `json:"anyOf,omitempty"`
	OneOf           []*Schema `json:"oneOf,omitempty"`

	If   *Schema `json:"if,omitempty"`
	Then *Schema `json:"then,omitempty"`
	Else *Schema `json:"else,omitempty"`

	Const string `json:"const,omitempty"`
	// contains filtered or unexported fields
}

Schema is a structure for JSON schema. JSON encoding of a Schema gives a valid JSON schema. http://json-schema.org

func NewSchema

func NewSchema() *Schema

NewSchema creates a new Schema. It's primarily for the convenience of initiating struct maps.

func (*Schema) MarshalJSON

func (s *Schema) MarshalJSON() ([]byte, error)

MarshalJSON allows to marshal Schema.Type as string or list