chaff

README

go-chaff

A Json Schema Faker for Go 🙈.

It will generate matching random for a given JSON schema

Installation

go get github.com/ryanolee/go-chaff@1

Usage

package main

import (
	"encoding/json"
	"fmt"

	"github.com/ryanolee/go-chaff"
)

const schema = `{"type": "number"}`

func main() {
	generator, err := chaff.ParseSchemaStringWithDefaults(schema)
	if err != nil {
		panic(err)
	}
	
	fmt.Println(generator.Metadata.Errors)
	result := generator.GenerateWithDefaults()
	if err != nil {
		panic(err)
	}

	res, err := json.Marshal(result)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(res))
}

CLI

There is also a cli tool available for this package that can be installed from the releases section.

Usage: go-chaff [flags]
  -file string
        Specify a file path to read the JSON Schema from
  -format
        Format JSON output.
  -help
        Print out help.
  -output string
        Specify file path to write generated output to.
  -verbose
        Print out detailed error information.
  -version
        Print out cli version information.

You can also pipe into STDIN for the cli

echo '{"type": "string", "format": "ipv4"}' | go-chaff
"217.2.244.95"

Current support:

• Strings: (Including pattern through regen and formats through go faker)
• Number / Integer: multipleOf, min, max, exclusiveMin, exclusiveMax
• Constant types: enum, const, null
• References: $ref, $defs, definitions, $id
• object: properties, patternProperties, additionalProperties, minProperties, maxProperties, required
• Array: items, minItems, maxItems, contains, minContains, maxContains, prefixItems, additionalItems
• Combination types (anyOf / oneOf / allOf) N.b These are experimental! Expect none compliant schema output for some of these

Credits / Dependencies

• Regen (@zach-klippenstein and @AnatolyRugalev)
• Faker
• Schema Store
• Original idea, inspiration and technical support json-schema-faker

What is left to do?

• Better test coverage (Property based and unit of various generators)
• Handle many edge cases where this package might not generate schema compliant results
• Overcome the limitations of the current oneOf, anyOf and allOf keywords implementation.
• Add support for if / else keywords

Documentation

Index

• type Generator
• type GeneratorOptions
• type ParserOptions
• type RootGenerator
  • func ParseSchema(schema []byte, opts *ParserOptions) (RootGenerator, error)
  • func ParseSchemaFile(path string, opts *ParserOptions) (RootGenerator, error)
  • func ParseSchemaFileWithDefaults(path string) (RootGenerator, error)
  • func ParseSchemaString(schema string, opts *ParserOptions) (RootGenerator, error)
  • func ParseSchemaStringWithDefaults(schema string) (RootGenerator, error)
  • func ParseSchemaWithDefaults(schema []byte) (RootGenerator, error)
  • func (g RootGenerator) Generate(opts *GeneratorOptions) interface{}
  • func (g RootGenerator) GenerateWithDefaults() interface{}
  • func (g RootGenerator) String() string

Types

type Generator

type Generator interface {
	fmt.Stringer
	Generate(*GeneratorOptions) interface{}
}

type GeneratorOptions

type GeneratorOptions struct {
	// The source of randomness to use for the given generation.
	// Please note that some parts of the generators use different sources of randomness.
	// ("regex" generation and "format" strings)
	Rand *rand.RandUtil

	// The default minimum number value
	DefaultNumberMinimum int

	// The default maximum number value
	DefaultNumberMaximum int

	// The default minimum String length
	DefaultStringMinLength int

	// The default maximum String length
	DefaultStringMaxLength int

	// The default minimum array length
	DefaultArrayMinItems int

	// The default maximum array length
	// This will be set min + this inf the event a minimum value is set
	DefaultArrayMaxItems int

	// The default minimum object properties (Will be ignored if there are fewer properties available)
	DefaultObjectMinProperties int

	// The default maximum object properties (Will be ignored if there are fewer properties available)
	DefaultObjectMaxProperties int

	// The maximum number of references to resolve at once (Default: 10)
	MaximumReferenceDepth int

	// In the event that schemas are recursive there is a good chance the generator
	// can run forever. This option will bypass the check for cyclic references
	// Please defer to the MaximumReferenceDepth option if possible when using this
	BypassCyclicReferenceCheck bool

	// Used to keep track of references during a resolution cycle (Used internally and can be ignored)
	ReferenceResolver referenceResolver

	// Though technically in some cases a schema may allow for additional
	// values it might not always be desireable. this option suppresses fallback_n values
	// so that they will only appear to make up a "minimum value" forces them to
	SuppressFallbackValues bool
}

type ParserOptions

type ParserOptions struct {
	// Options for the regex generator used for generating strings with the "pattern property"
	RegexStringOptions *regen.GeneratorArgs

	// Options for the regex generator used for pattern properties
	RegexPatternPropertyOptions *regen.GeneratorArgs
}

Options to take into account when parsing a json schema

type RootGenerator

type RootGenerator struct {
	Generator Generator
	// For any "$defs"
	Defs map[string]Generator
	// For any "definitions"
	Definitions map[string]Generator
	// Metadata related to parser operations
	Metadata *parserMetadata
}

Root generator a given schema. Call the Generate method on this to generate a value

func ParseSchema

func ParseSchema(schema []byte, opts *ParserOptions) (RootGenerator, error)

Parses a Json Schema byte array. If there is an error parsing the schema, an error will be returned.

func ParseSchemaFile

func ParseSchemaFile(path string, opts *ParserOptions) (RootGenerator, error)

Parses a Json Schema file at the given path. If there is an error reading the file or parsing the schema, an error will be returned

func ParseSchemaFileWithDefaults

func ParseSchemaFileWithDefaults(path string) (RootGenerator, error)

Parses a Json Schema file at the given path with default options. If there is an error reading the file or parsing the schema, an error will be returned

func ParseSchemaString

func ParseSchemaString(schema string, opts *ParserOptions) (RootGenerator, error)

Parses a Json Schema string. If there is an error parsing the schema, an error will be returned.

func ParseSchemaStringWithDefaults

func ParseSchemaStringWithDefaults(schema string) (RootGenerator, error)

func ParseSchemaWithDefaults

func ParseSchemaWithDefaults(schema []byte) (RootGenerator, error)

Parses a Json Schema byte array with default options. If there is an error parsing the schema, an error will be returned.

func (RootGenerator) Generate

func (g RootGenerator) Generate(opts *GeneratorOptions) interface{}

Generates values based on the passed options

func (RootGenerator) GenerateWithDefaults

func (g RootGenerator) GenerateWithDefaults() interface{}

func (RootGenerator) String

func (g RootGenerator) String() string