Skip to content
Simple library and command line program for converting between BSON, JSON, YAML, TOML, and many more common serialization formats.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

CircleCI Go Report Card GoDoc license



go-simple-serializer (aka GSS) is a simple library for serializing/deserializing objects.

GSS supports bson, csv, tsv, hcl, hcl2, json, jsonl, properties, toml, yaml. hcl and hcl2 implementation is fragile and very much in alpha.

Using cross compilers, this library can also be called by other languages. This library is cross compiled into a Shared Object file (*.so). The Shared Object file can be called by C, C++, and Python on Linux machines. See the examples folder for patterns that you can use. This library is also compiled to pure JavaScript using GopherJS.



You can use the command line tool to convert between serialization formats.

gss is a simple program for serializing/deserializing data.

  gss [flags]
  gss [command]

Available Commands:
  completion  Generates bash completion scripts
  help        Help about any command
  version     print version information to stdout

  -a, --async                   async processing
  -h, --help                    help for gss
  -c, --input-comment string    The input comment character, e.g., #.  Commented lines are not sent to output.
  -i, --input-format string     The input format: bson, csv, tsv, hcl, hcl2, json, jsonl, properties, toml, yaml
      --input-header strings    The input header if the stdin input has no header.
      --input-lazy-quotes       allows lazy quotes for CSV and TSV
  -l, --input-limit int         The input limit (default -1)
      --input-skip-lines int    The number of lines to skip before processing
  -t, --input-trim              trim input lines
  -o, --output-format string    The output format: bson, csv, tsv, hcl, hcl2, json, jsonl, properties, toml, yaml
      --output-header strings   The output header if the stdout output has no header.
  -n, --output-limit int        the output limit (default -1)
  -p, --output-pretty           print pretty output
  -s, --output-sorted           sort output
      --verbose                 Print debug info to stdout

Use "gss [command] --help" for more information about a command.


You can import go-simple-serializer as a library with:

import (

The Convert, Deserialize, and Serialize functions are the core functions to use.

  output_string, err := gss.Convert(input_string, input_format, input_header, input_comment, output_format, verbose)
  input_type, err := GetType(input_string, input_format)
	if err != nil {
		return "", errors.Wrap(err, "error creating new object for format "+input_format)
  output, err := gss.Deserialize(input, format, input_header, input_comment, input_type, verbose)
  output_string, err := gss.Serialize(input, format)

See gss in GoDoc for information on how to use Go API.


    <script src="https://...gss.js"></script>
      var input = "{\"a\":1}";
      var output = gss.convert(input, "json", "yaml", )
      // You can also pass the input header for a csv/tsv that has none
      var output = gss.convert(input, "csv", "json", {"header": ["a","b"]})


The go-simple-serializer code is available for use in Android applications under com.spatialcurrent.gss. For example,

import com.spatialcurrent.gss.Gss;
  String output_format = Gss.convert(input_string, input_format, input_header, input_comment, output_format, verbose);


A variant of the Convert function is exported in a Shared Object file (*.so), which can be called by C, C++, and Python programs on Linux machines. For example:

char *input_string = "<YOUR INPUT>";
char *output_string;
err = Convert(input_string, input_format, input_header_csv, input_comment, output_format, &output_string);

The Go function definition defined in plugins/gss/main.go uses *C.char for all input except output_string which uses a double pointer (**C.char) to write to the output.

func Convert(input_string *C.char, input_format *C.char, input_header *C.char, input_comment *C.char, output_format *C.char, output_string **C.char) *C.char

For complete patterns for C, C++, and Python, see the go-simpler-serializer/examples folder.


go-simple-serializer is currently in alpha. See releases at


.gitignore file to jsonl

cat .gitignore | ./gss -i csv -h pattern -o jsonl

Get language from .travis.yml and set to variable

language=$(cat .travis.yml | ./gss_linux_amd64 -i yaml -o json -c '#' | jq .language -r)



The make build_cli script is used to build executables for Linux and Windows.


You can compile GSS to pure JavaScript with the make build_javascript script.


The make build_android script is used to build an Android Archive (AAR) file and associated Javadocs.

Shared Object

The make build_so script is used to build a Shared Object (*.go), which can be called by C, C++, and Python on Linux machines.

Changing Destination

The default destination for build artifacts is go-simple-serializer/bin, but you can change the destination with an environment variable. For building on a Chromebook consider saving the artifacts in /usr/local/go/bin, e.g., DEST=/usr/local/go/bin make build_cli


Spatial Current, Inc. is currently accepting pull requests for this repository. We'd love to have your contributions! Please see for how to get started.


This work is distributed under the MIT License. See LICENSE file.

You can’t perform that action at this time.