{"id":13687668,"url":"https://github.com/google/jsonapi","last_synced_at":"2025-05-13T21:05:56.867Z","repository":{"id":34663552,"uuid":"38635217","full_name":"google/jsonapi","owner":"google","description":"jsonapi.org style payload serializer and deserializer","archived":false,"fork":false,"pushed_at":"2024-07-02T14:03:51.000Z","size":332,"stargazers_count":1431,"open_issues_count":67,"forks_count":215,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-04-28T13:58:42.763Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://godoc.org/github.com/google/jsonapi","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/google.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-07-06T17:40:39.000Z","updated_at":"2025-04-28T03:47:29.000Z","dependencies_parsed_at":"2023-01-16T23:00:27.646Z","dependency_job_id":"46894ddd-c758-4053-a258-70c8c4c4a016","html_url":"https://github.com/google/jsonapi","commit_stats":{"total_commits":189,"total_committers":35,"mean_commits":5.4,"dds":0.6825396825396826,"last_synced_commit":"1e07b10d47d02b07ccaa2dfc5ceec143bdd81c14"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fjsonapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fjsonapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fjsonapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fjsonapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/google","download_url":"https://codeload.github.com/google/jsonapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254028639,"owners_count":22002277,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T15:00:58.361Z","updated_at":"2025-05-13T21:05:51.851Z","avatar_url":"https://github.com/google.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# jsonapi\n\n[![Build Status](https://travis-ci.org/google/jsonapi.svg?branch=master)](https://travis-ci.org/google/jsonapi)\n[![Go Report Card](https://goreportcard.com/badge/github.com/google/jsonapi)](https://goreportcard.com/report/github.com/google/jsonapi)\n[![GoDoc](https://godoc.org/github.com/google/jsonapi?status.svg)](http://godoc.org/github.com/google/jsonapi)\n[![No Maintenance Intended](http://unmaintained.tech/badge.svg)](http://unmaintained.tech/)\n\nA serializer/deserializer for JSON payloads that comply to the\n[JSON API - jsonapi.org](http://jsonapi.org) spec in go.\n\n\n\n## Installation\n\n```\ngo get -u github.com/google/jsonapi\n```\n\nOr, see [Alternative Installation](#alternative-installation).\n\n## Background\n\nYou are working in your Go web application and you have a struct that is\norganized similarly to your database schema.  You need to send and\nreceive json payloads that adhere to the JSON API spec.  Once you realize that\nyour json needed to take on this special form, you go down the path of\ncreating more structs to be able to serialize and deserialize JSON API\npayloads.  Then there are more models required with this additional\nstructure.  Ugh! With JSON API, you can keep your model structs as is and\nuse [StructTags](http://golang.org/pkg/reflect/#StructTag) to indicate\nto JSON API how you want your response built or your request\ndeserialized.  What about your relationships?  JSON API supports\nrelationships out of the box and will even put them in your response\ninto an `included` side-loaded slice--that contains associated records.\n\n## Introduction\n\nJSON API uses [StructField](http://golang.org/pkg/reflect/#StructField)\ntags to annotate the structs fields that you already have and use in\nyour app and then reads and writes [JSON API](http://jsonapi.org)\noutput based on the instructions you give the library in your JSON API\ntags.  Let's take an example.  In your app, you most likely have structs\nthat look similar to these:\n\n\n```go\ntype Blog struct {\n\tID            int       `json:\"id\"`\n\tTitle         string    `json:\"title\"`\n\tPosts         []*Post   `json:\"posts\"`\n\tCurrentPost   *Post     `json:\"current_post\"`\n\tCurrentPostId int       `json:\"current_post_id\"`\n\tCreatedAt     time.Time `json:\"created_at\"`\n\tViewCount     int       `json:\"view_count\"`\n}\n\ntype Post struct {\n\tID       int        `json:\"id\"`\n\tBlogID   int        `json:\"blog_id\"`\n\tTitle    string     `json:\"title\"`\n\tBody     string     `json:\"body\"`\n\tComments []*Comment `json:\"comments\"`\n}\n\ntype Comment struct {\n\tId     int    `json:\"id\"`\n\tPostID int    `json:\"post_id\"`\n\tBody   string `json:\"body\"`\n\tLikes  uint   `json:\"likes_count,omitempty\"`\n}\n```\n\nThese structs may or may not resemble the layout of your database.  But\nthese are the ones that you want to use right?  You wouldn't want to use\nstructs like those that JSON API sends because it is difficult to get at\nall of your data easily.\n\n## Example App\n\n[examples/app.go](https://github.com/google/jsonapi/blob/master/examples/app.go)\n\nThis program demonstrates the implementation of a create, a show,\nand a list [http.Handler](http://golang.org/pkg/net/http#Handler).  It\noutputs some example requests and responses as well as serialized\nexamples of the source/target structs to json.  That is to say, I show\nyou that the library has successfully taken your JSON API request and\nturned it into your struct types.\n\nTo run,\n\n* Make sure you have [Go installed](https://golang.org/doc/install)\n* Create the following directories or similar: `~/go`\n* Set `GOPATH` to `PWD` in your shell session, `export GOPATH=$PWD`\n* `go get github.com/google/jsonapi`.  (Append `-u` after `get` if you\n  are updating.)\n* `cd $GOPATH/src/github.com/google/jsonapi/examples`\n* `go build \u0026\u0026 ./examples`\n\n## `jsonapi` Tag Reference\n\n### Example\n\nThe `jsonapi` [StructTags](http://golang.org/pkg/reflect/#StructTag)\ntells this library how to marshal and unmarshal your structs into\nJSON API payloads and your JSON API payloads to structs, respectively.\nThen Use JSON API's Marshal and Unmarshal methods to construct and read\nyour responses and replies.  Here's an example of the structs above\nusing JSON API tags:\n\n```go\ntype Blog struct {\n\tID            int       `jsonapi:\"primary,blogs\"`\n\tTitle         string    `jsonapi:\"attr,title\"`\n\tPosts         []*Post   `jsonapi:\"relation,posts\"`\n\tCurrentPost   *Post     `jsonapi:\"relation,current_post\"`\n\tCurrentPostID int       `jsonapi:\"attr,current_post_id\"`\n\tCreatedAt     time.Time `jsonapi:\"attr,created_at\"`\n\tViewCount     int       `jsonapi:\"attr,view_count\"`\n}\n\ntype Post struct {\n\tID       int        `jsonapi:\"primary,posts\"`\n\tBlogID   int        `jsonapi:\"attr,blog_id\"`\n\tTitle    string     `jsonapi:\"attr,title\"`\n\tBody     string     `jsonapi:\"attr,body\"`\n\tComments []*Comment `jsonapi:\"relation,comments\"`\n}\n\ntype Comment struct {\n\tID     int    `jsonapi:\"primary,comments\"`\n\tPostID int    `jsonapi:\"attr,post_id\"`\n\tBody   string `jsonapi:\"attr,body\"`\n\tLikes  uint   `jsonapi:\"attr,likes-count,omitempty\"`\n}\n```\n\n### Permitted Tag Values\n\n#### `primary`\n\n```\n`jsonapi:\"primary,\u003ctype field output\u003e\"`\n```\n\nThis indicates this is the primary key field for this struct type.\nTag value arguments are comma separated.  The first argument must be,\n`primary`, and the second must be the name that should appear in the\n`type`\\* field for all data objects that represent this type of model.\n\n\\* According the [JSON API](http://jsonapi.org) spec, the plural record\ntypes are shown in the examples, but not required.\n\n#### `attr`\n\n```\n`jsonapi:\"attr,\u003ckey name in attributes hash\u003e,\u003coptional: omitempty\u003e\"`\n```\n\nThese fields' values will end up in the `attributes`hash for a record.\nThe first argument must be, `attr`, and the second should be the name\nfor the key to display in the `attributes` hash for that record. The optional\nthird argument is `omitempty` - if it is present the field will not be present\nin the `\"attributes\"` if the field's value is equivalent to the field types\nempty value (ie if the `count` field is of type `int`, `omitempty` will omit the\nfield when `count` has a value of `0`). Lastly, the spec indicates that\n`attributes` key names should be dasherized for multiple word field names.\n\n#### `relation`\n\n```\n`jsonapi:\"relation,\u003ckey name in relationships hash\u003e,\u003coptional: omitempty\u003e\"`\n```\n\nRelations are struct fields that represent a one-to-one or one-to-many\nrelationship with other structs. JSON API will traverse the graph of\nrelationships and marshal or unmarshal records.  The first argument must\nbe, `relation`, and the second should be the name of the relationship,\nused as the key in the `relationships` hash for the record. The optional\nthird argument is `omitempty` - if present will prevent non existent to-one and\nto-many from being serialized.\n\n## Methods Reference\n\n**All `Marshal` and `Unmarshal` methods expect pointers to struct\ninstance or slices of the same contained with the `interface{}`s**\n\nNow you have your structs prepared to be serialized or materialized, What\nabout the rest?\n\n### Create Record Example\n\nYou can Unmarshal a JSON API payload using\n[jsonapi.UnmarshalPayload](http://godoc.org/github.com/google/jsonapi#UnmarshalPayload).\nIt reads from an [io.Reader](https://golang.org/pkg/io/#Reader)\ncontaining a JSON API payload for one record (but can have related\nrecords).  Then, it materializes a struct that you created and passed in\n(using new or \u0026).  Again, the method supports single records only, at\nthe top level, in request payloads at the moment. Bulk creates and\nupdates are not supported yet.\n\nAfter saving your record, you can use,\n[MarshalOnePayload](http://godoc.org/github.com/google/jsonapi#MarshalOnePayload),\nto write the JSON API response to an\n[io.Writer](https://golang.org/pkg/io/#Writer).\n\n#### `UnmarshalPayload`\n\n```go\nUnmarshalPayload(in io.Reader, model interface{})\n```\n\nVisit [godoc](http://godoc.org/github.com/google/jsonapi#UnmarshalPayload)\n\n#### `MarshalPayload`\n\n```go\nMarshalPayload(w io.Writer, models interface{}) error\n```\n\nVisit [godoc](http://godoc.org/github.com/google/jsonapi#MarshalPayload)\n\nWrites a JSON API response, with related records sideloaded, into an\n`included` array.  This method encodes a response for either a single record or\nmany records.\n\n##### Handler Example Code\n\n```go\nfunc CreateBlog(w http.ResponseWriter, r *http.Request) {\n\tblog := new(Blog)\n\n\tif err := jsonapi.UnmarshalPayload(r.Body, blog); err != nil {\n\t\thttp.Error(w, err.Error(), http.StatusInternalServerError)\n\t\treturn\n\t}\n\n\t// ...save your blog...\n\n\tw.Header().Set(\"Content-Type\", jsonapi.MediaType)\n\tw.WriteHeader(http.StatusCreated)\n\n\tif err := jsonapi.MarshalPayload(w, blog); err != nil {\n\t\thttp.Error(w, err.Error(), http.StatusInternalServerError)\n\t}\n}\n```\n\n### Create Records Example\n\n#### `UnmarshalManyPayload`\n\n```go\nUnmarshalManyPayload(in io.Reader, t reflect.Type) ([]interface{}, error)\n```\n\nVisit [godoc](http://godoc.org/github.com/google/jsonapi#UnmarshalManyPayload)\n\nTakes an `io.Reader` and a `reflect.Type` representing the uniform type\ncontained within the `\"data\"` JSON API member.\n\n##### Handler Example Code\n\n```go\nfunc CreateBlogs(w http.ResponseWriter, r *http.Request) {\n\t// ...create many blogs at once\n\n\tblogs, err := UnmarshalManyPayload(r.Body, reflect.TypeOf(new(Blog)))\n\tif err != nil {\n\t\tt.Fatal(err)\n\t}\n\n\tfor _, blog := range blogs {\n\t\tb, ok := blog.(*Blog)\n\t\t// ...save each of your blogs\n\t}\n\n\tw.Header().Set(\"Content-Type\", jsonapi.MediaType)\n\tw.WriteHeader(http.StatusCreated)\n\n\tif err := jsonapi.MarshalPayload(w, blogs); err != nil {\n\t\thttp.Error(w, err.Error(), http.StatusInternalServerError)\n\t}\n}\n```\n\n\n### Links\n\nIf you need to include [link objects](http://jsonapi.org/format/#document-links) along with response data, implement the `Linkable` interface for document-links, and `RelationshipLinkable` for relationship links:\n\n```go\nfunc (post Post) JSONAPILinks() *Links {\n\treturn \u0026Links{\n\t\t\"self\": \"href\": fmt.Sprintf(\"https://example.com/posts/%d\", post.ID),\n\t\t\"comments\": Link{\n\t\t\tHref: fmt.Sprintf(\"https://example.com/api/blogs/%d/comments\", post.ID),\n\t\t\tMeta: map[string]interface{}{\n\t\t\t\t\"counts\": map[string]uint{\n\t\t\t\t\t\"likes\":    4,\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t}\n}\n\n// Invoked for each relationship defined on the Post struct when marshaled\nfunc (post Post) JSONAPIRelationshipLinks(relation string) *Links {\n\tif relation == \"comments\" {\n\t\treturn \u0026Links{\n\t\t\t\"related\": fmt.Sprintf(\"https://example.com/posts/%d/comments\", post.ID),\n\t\t}\n\t}\n\treturn nil\n}\n```\n\n### Meta\n\n If you need to include [meta objects](http://jsonapi.org/format/#document-meta) along with response data, implement the `Metable` interface for document-meta, and `RelationshipMetable` for relationship meta:\n\n ```go\nfunc (post Post) JSONAPIMeta() *Meta {\n\treturn \u0026Meta{\n\t\t\"details\": \"sample details here\",\n\t}\n}\n\n// Invoked for each relationship defined on the Post struct when marshaled\nfunc (post Post) JSONAPIRelationshipMeta(relation string) *Meta {\n\tif relation == \"comments\" {\n\t\treturn \u0026Meta{\n\t\t\t\"this\": map[string]interface{}{\n\t\t\t\t\"can\": map[string]interface{}{\n\t\t\t\t\t\"go\": []interface{}{\n\t\t\t\t\t\t\"as\",\n\t\t\t\t\t\t\"deep\",\n\t\t\t\t\t\tmap[string]interface{}{\n\t\t\t\t\t\t\t\"as\": \"required\",\n\t\t\t\t\t\t},\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t},\n\t\t}\n\t}\n\treturn nil\n}\n```\n\n### Custom types\n\nCustom types are supported for primitive types, only, as attributes.  Examples,\n\n```go\ntype CustomIntType int\ntype CustomFloatType float64\ntype CustomStringType string\n```\n\nTypes like following are not supported, but may be in the future:\n\n```go\ntype CustomMapType map[string]interface{}\ntype CustomSliceMapType []map[string]interface{}\n```\n\n### Errors\nThis package also implements support for JSON API compatible `errors` payloads using the following types.\n\n#### `MarshalErrors`\n```go\nMarshalErrors(w io.Writer, errs []*ErrorObject) error\n```\n\nWrites a JSON API response using the given `[]error`.\n\n#### `ErrorsPayload`\n```go\ntype ErrorsPayload struct {\n\tErrors []*ErrorObject `json:\"errors\"`\n}\n```\n\nErrorsPayload is a serializer struct for representing a valid JSON API errors payload.\n\n#### `ErrorObject`\n```go\ntype ErrorObject struct { ... }\n\n// Error implements the `Error` interface.\nfunc (e *ErrorObject) Error() string {\n\treturn fmt.Sprintf(\"Error: %s %s\\n\", e.Title, e.Detail)\n}\n```\n\nErrorObject is an `Error` implementation as well as an implementation of the JSON API error object.\n\nThe main idea behind this struct is that you can use it directly in your code as an error type and pass it directly to `MarshalErrors` to get a valid JSON API errors payload.\n\n##### Errors Example Code\n```go\n// An error has come up in your code, so set an appropriate status, and serialize the error.\nif err := validate(\u0026myStructToValidate); err != nil {\n\tcontext.SetStatusCode(http.StatusBadRequest) // Or however you need to set a status.\n\tjsonapi.MarshalErrors(w, []*ErrorObject{{\n\t\tTitle: \"Validation Error\",\n\t\tDetail: \"Given request body was invalid.\",\n\t\tStatus: \"400\",\n\t\tMeta: map[string]interface{}{\"field\": \"some_field\", \"error\": \"bad type\", \"expected\": \"string\", \"received\": \"float64\"},\n\t}})\n\treturn\n}\n```\n\n## Testing\n\n### `MarshalOnePayloadEmbedded`\n\n```go\nMarshalOnePayloadEmbedded(w io.Writer, model interface{}) error\n```\n\nVisit [godoc](http://godoc.org/github.com/google/jsonapi#MarshalOnePayloadEmbedded)\n\nThis method is not strictly meant to for use in implementation code,\nalthough feel free.  It was mainly created for use in tests; in most cases,\nyour request payloads for create will be embedded rather than sideloaded\nfor related records.  This method will serialize a single struct pointer\ninto an embedded json response.  In other words, there will be no,\n`included`, array in the json; all relationships will be serialized\ninline with the data.\n\nHowever, in tests, you may want to construct payloads to post to create\nmethods that are embedded to most closely model the payloads that will\nbe produced by the client.  This method aims to enable that.\n\n### Example\n\n```go\nout := bytes.NewBuffer(nil)\n\n// testModel returns a pointer to a Blog\njsonapi.MarshalOnePayloadEmbedded(out, testModel())\n\nh := new(BlogsHandler)\n\nw := httptest.NewRecorder()\nr, _ := http.NewRequest(http.MethodPost, \"/blogs\", out)\n\nh.CreateBlog(w, r)\n\nblog := new(Blog)\njsonapi.UnmarshalPayload(w.Body, blog)\n\n// ... assert stuff about blog here ...\n```\n\n## Alternative Installation\nI use git subtrees to manage dependencies rather than `go get` so that\nthe src is committed to my repo.\n\n```\ngit subtree add --squash --prefix=src/github.com/google/jsonapi https://github.com/google/jsonapi.git master\n```\n\nTo update,\n\n```\ngit subtree pull --squash --prefix=src/github.com/google/jsonapi https://github.com/google/jsonapi.git master\n```\n\nThis assumes that I have my repo structured with a `src` dir containing\na collection of packages and `GOPATH` is set to the root\nfolder--containing `src`.\n\n## Contributing\n\nFork, Change, Pull Request *with tests*.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle%2Fjsonapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogle%2Fjsonapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle%2Fjsonapi/lists"}