Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

A Go JSONAPI Specification Handler

GoDoc Travis CI Go Report Card TestCoverage

A (de)serialization handler for writing JSON API Specification compatible software in Go. Works with Ember/Ember-Data too!


  1. JSH
  1. JSC
  2. JSH-API

jsh - JSON Specification Handler

For streamlined JSONAPI object serialization. Uses govalidator for input validation.


type User struct {
  // valid from gives us input validation
  // when object.Unmarshal() is invoked on this type
  Name string `json:"name" valid:"alphanum"`

// example http.HandlerFunc for PATCH /users/1
func PatchUser(w http.ResponseWriter, r *http.Request) {

  // performs Specification checks against the request
  object, err := jsh.ParseObject(r)
  if err != nil {
    // jsh returns API friendly errors, that are easy to respond with
    jsh.Send(w, r, err)

  // use object.ID to look up user/do business logic
  user := &User{}
  // unmarshal data into relevant internal types if govalidator passes, otherwise
  // return the pre-formatted HTTP 422 error to signify how the input failed
  err = object.Unmarshal("users", user)
  if err != nil {
    jsh.Send(w, r, err)

  // modify your resource object
  user.Name = "Bob"

  // repackage and send the updated resource as a response
  err = object.Marshal(user)
  if err != nil {
    jsh.Send(w, r, err)

  jsh.Send(w, r, object)

Motivation for JSH

JSH was written for tackling the issue of dealing with Ember-Data within a pre-existing API server. In sticking with Go's philosophy of modules over frameworks, it is intended to be a drop in serialization layer focusing only on parsing, validating, and sending JSONAPI compatible responses.



- Handles both single object and array based JSON requests and responses
- Input validation with HTTP 422 Status support via [go-validator](
- Client request validation with HTTP 406 Status responses
- Links, Relationship, Meta fields
- Prepackaged error responses, easy to use Internal Service Error builder
- Smart responses with correct HTTP Statuses based on Request Method and HTTP Headers


- [Reserved character checking](

Not Implementing:

* These features aren't handled because they are beyond the scope of what
  this module is meant to achieve. See [jshapi](
  for a full-fledged API solution that solves many of these problems.

- Routing
- Sorting
- Pagination
- Filtering


jsh has a mostly stabilized core data document model. At this point in time I am not yet ready to declare v1, but am actively trying to avoid breaking the public API. The areas most likely to receive improvement include relationship, link, and metadata management. At this point in time I can confidentally suggest you use jsh without risking major upgrade incompatibility going forward!

jsc - JSON Specification Client

A HTTP JSONAPI Client for making outbound server requests. Built on top of http.Client and jsh:


// GET http://your.api/users/1
document, resp, err := jsc.Fetch("http://your.api/", "users", "1")
object := doc.First()

user := &yourUser{}
err := object.Unmarshal("users", user)


If you're looking for a good place to start with a new API, I've since created jshapi which builds on top of Goji 2 and jsh in order to handle the routing structure that JSON API requires as well as a number of other useful tools for testing and mocking APIs as you develop your own projects. JSHAPI is similar in spirit to this project as it inteniontally focuses on eliminating boilerplate from your projects without trying to solve all of the world's problems.


There are lots of great examples in the tests themselves that show exactly how jsh works. The godocs as linked above have a number of examples in them as well.