This repo was moved at 20140912-1451 to [go-goodies/go_jsoncfg] (


A Go library for reading configuration settings from JSON files.


$ go get


jsoncfgo can handle the following data types from the .json configuration file that it reads:

  • bool
  • int
  • int64
  • string
  • []string
  • []int64

You can also call the Validate function to validate attempts to read non-existent variables.

jsconfgo Advanced Features
  • Read environment variables
  • Handle included file objects that refer to other config files
  • Handle nested json objects within the config file
  • Validation:
    • Validate existence of required variables
    • Validate attempt to read non-existent variable


   "host": "localhost",
   "port": 5432,
   "bignNumber": 999999999999999,
   "active": true,
   "appList": ["myapp", "sharedapp"],
   "numbers": [9, 8, 7, 6]
package main

import (

func main() {

	cfg := jsoncfgo.Load("/Users/lex/dev/go/data/jsoncfgo/simple-config.json")

	host := cfg.String("host")
	fmt.Printf("host: %v\n", host)
	bogusHost := cfg.String("bogusHost", "default_host_name")
	fmt.Printf("host: %v\n\n", bogusHost)

	port := cfg.Int("port")
	fmt.Printf("port: %v\n", port)
	bogusPort := cfg.Int("bogusPort", 9000)
	fmt.Printf("bogusPort: %v\n\n", bogusPort)

	bigNumber := cfg.Int64("bignNumber")
	fmt.Printf("bigNumber: %v\n", bigNumber)
	bogusBigNumber := cfg.Int64("bogusBigNumber", 9000000000000000000)
	fmt.Printf("bogusBigNumber: %v\n\n", bogusBigNumber)

	active := cfg.Bool("active")
	fmt.Printf("active: %v\n", active)
	bogusFalseActive := cfg.Bool("bogusFalseActive", false)
	fmt.Printf("bogusFalseActive: %v\n", bogusFalseActive)
	bogusTrueActive := cfg.Bool("bogusTrueActive", true)
	fmt.Printf("bogusTrueActive: %v\n\n", bogusTrueActive)

	appList := cfg.List("appList")
	fmt.Printf("appList: %v\n", appList)
	bogusAppList := cfg.List("bogusAppList", []string{"app1", "app2", "app3"})
	fmt.Printf("bogusAppList: %v\n\n", bogusAppList)

	numbers := cfg.IntList("numbers")
	fmt.Printf("numbers: %v\n", numbers)
	bogusSettings := cfg.IntList("bogusSettings", []int64{1, 2, 3})
	fmt.Printf("bogusAppList: %v\n\n", bogusSettings)

	if err := cfg.Validate(); err != nil {
		time.Sleep(100 * time.Millisecond)
		defer log.Fatalf("ERROR - Invalid config file...\n%v", err)
host: localhost
host: default_host_name

port: 5432
bogusPort: 9000

bigNumber: 999999999999999
bogusBigNumber: 9000000000000000000

active: true
bogusFalseActive: false
bogusTrueActive: true

appList: [myapp sharedapp]
bogusAppList: [app1 app2 app3]

numbers: [9 8 7 6]
bogusAppList: [1 2 3]

2014/07/25 19:25:03 ERROR - Invalid config file...
Multiple errors: Missing required config key "bogusAppList" (list of strings), Missing required config key "bogusSettings" (list of ints)
exit status 1

Process finished with exit code 1


See interface documenation at [package jsoncfgo] (

See companion article at [jsoncfgo - A JSON Config File Reader] (

For a code example of how to use some of the advanced features of jsoncfgo, see [jsoncfgo - Advanced Usage] (

Expand ▾ Collapse ▴



    Package jsoncfgo defines a helper type for JSON objects to be used for configuration.



    This section is empty.


    This section is empty.


    func RegisterFunc

    func RegisterFunc(name string, fn func(c *ConfigParser, v []interface{}) (interface{}, error))

      RegisterFunc registers a new function that may be called from JSON configs using an array of the form ["_name", arg0, argN...]. The provided name must begin with an underscore.


      type ConfigParser

      type ConfigParser struct {
      	// Open optionally specifies an opener function.
      	Open func(filename string) (File, error)
      	// IncludeDirs optionally specifies where to find the other config files which are child
      	// objects of this config, if any. Even if nil, the working directory is always searched
      	// first.
      	IncludeDirs []string
      	// contains filtered or unexported fields

        ConfigParser specifies the environment for parsing a config file and evaluating expressions.

        func (*ConfigParser) CheckTypes

        func (c *ConfigParser) CheckTypes(m map[string]interface{}) error

          CheckTypes parses m and returns an error if it encounters a type or value that is not supported by this package.

          func (*ConfigParser) ConfigFilePath

          func (c *ConfigParser) ConfigFilePath(configFile string) (path string, err error)

            ConfigFilePath checks if configFile is found and returns a usable path to it. It first checks if configFile is an absolute path, or if it's found in the current working directory. If not, it then checks if configFile is in one of c.IncludeDirs. It returns an error if configFile is absolute and could not be statted, or os.ErrNotExist if configFile was not found.

            func (*ConfigParser) ReadFile

            func (c *ConfigParser) ReadFile(path string) (Obj, error)

              ReadFile parses the provided path and returns the config file. If path is empty, the c.Open function must be defined.

              type File

              type File interface {
              	Name() string

                A File is the type returned by ConfigParser.Open.

                type Obj

                type Obj map[string]interface{}

                  Obj is a JSON configuration map.

                  func Load

                  func Load(configPath string) Obj

                    Load calls ReadFile to read json config data from the file specified by configPath If an error occurs, it will log the error.

                    func ReadFile

                    func ReadFile(configPath string) (Obj, error)

                      Reads json config data from the specified open file, expanding all expressions

                      func (Obj) Bool

                      func (jc Obj) Bool(key string, args ...interface{}) bool

                        Bool is an OptionalBool

                        func (Obj) Int

                        func (jc Obj) Int(key string, args ...interface{}) int

                          Int is an OptionalInt

                          func (Obj) Int64

                          func (jc Obj) Int64(key string, args ...interface{}) int64

                            Int64 is an Optional Int64

                            func (Obj) IntList

                            func (jc Obj) IntList(key string, args ...interface{}) []int64

                              List accepts and optional parameter of type []int64

                              func (Obj) List

                              func (jc Obj) List(key string, args ...interface{}) []string

                                List accepts and optional parameter of type []string

                                func (Obj) Object

                                func (jc Obj) Object(key string) Obj

                                  Object is an OptionalObject

                                  func (Obj) OptionalBool

                                  func (jc Obj) OptionalBool(key string, def bool) bool

                                  func (Obj) OptionalInt

                                  func (jc Obj) OptionalInt(key string, def int) int

                                  func (Obj) OptionalInt64

                                  func (jc Obj) OptionalInt64(key string, def int64) int64

                                  func (Obj) OptionalList

                                  func (jc Obj) OptionalList(key string) []string

                                  func (Obj) OptionalObject

                                  func (jc Obj) OptionalObject(key string) Obj

                                  func (Obj) OptionalString

                                  func (jc Obj) OptionalString(key, def string) string

                                  func (Obj) OptionalStringOrObject

                                  func (jc Obj) OptionalStringOrObject(key string) interface{}

                                  func (Obj) OptionalUint

                                  func (jc Obj) OptionalUint(key string, def uint) uint

                                  func (Obj) RequiredBool

                                  func (jc Obj) RequiredBool(key string) bool

                                  func (Obj) RequiredInt

                                  func (jc Obj) RequiredInt(key string) int

                                  func (Obj) RequiredInt64

                                  func (jc Obj) RequiredInt64(key string) int64

                                  func (Obj) RequiredList

                                  func (jc Obj) RequiredList(key string) []string

                                  func (Obj) RequiredObject

                                  func (jc Obj) RequiredObject(key string) Obj

                                  func (Obj) RequiredString

                                  func (jc Obj) RequiredString(key string) string

                                  func (Obj) RequiredStringOrObject

                                  func (jc Obj) RequiredStringOrObject(key string) interface{}

                                  func (Obj) RequiredUint

                                  func (jc Obj) RequiredUint(key string) uint

                                  func (Obj) String

                                  func (jc Obj) String(key string, args ...interface{}) string

                                    String is an OptionalString and accepts an optional string parameter

                                    func (Obj) StringOrObject

                                    func (jc Obj) StringOrObject(key string) interface{}

                                      StringOrObject is an OptionalStringOrObject

                                      func (Obj) Uint

                                      func (jc Obj) Uint(key string, args ...interface{}) uint

                                        Uint is an Optional Uint

                                        func (Obj) UnknownKeys

                                        func (jc Obj) UnknownKeys() []string

                                          UnknownKeys returns the keys from the config that have not yet been discovered by one of the RequiredT or OptionalT calls.

                                          func (Obj) Validate

                                          func (jc Obj) Validate() error