{"id":19054410,"url":"https://github.com/datadog/jsonapi","last_synced_at":"2025-04-04T19:15:10.939Z","repository":{"id":58391571,"uuid":"525027066","full_name":"DataDog/jsonapi","owner":"DataDog","description":"A marshaler/unmarshaler for JSON:API.","archived":false,"fork":false,"pushed_at":"2025-01-13T16:23:49.000Z","size":134,"stargazers_count":69,"open_issues_count":5,"forks_count":8,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-03-28T18:15:18.680Z","etag":null,"topics":["golang","jsonapi"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DataDog.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2022-08-15T14:51:20.000Z","updated_at":"2025-03-12T16:46:47.000Z","dependencies_parsed_at":"2024-03-14T19:27:36.235Z","dependency_job_id":"4322f8ea-2078-4a13-8e51-057186dcbb75","html_url":"https://github.com/DataDog/jsonapi","commit_stats":{"total_commits":34,"total_committers":8,"mean_commits":4.25,"dds":0.5882352941176471,"last_synced_commit":"7fcf2ea7a0040d9ad1f4ff6e3e44d7505fcce55c"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fjsonapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fjsonapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fjsonapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fjsonapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DataDog","download_url":"https://codeload.github.com/DataDog/jsonapi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247234923,"owners_count":20905854,"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":["golang","jsonapi"],"created_at":"2024-11-08T23:38:16.578Z","updated_at":"2025-04-04T19:15:10.922Z","avatar_url":"https://github.com/DataDog.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Go Reference](https://pkg.go.dev/badge/github.com/DataDog/jsonapi.svg)](https://pkg.go.dev/github.com/DataDog/jsonapi)\n[![test](https://github.com/DataDog/jsonapi/actions/workflows/test.yml/badge.svg)](https://github.com/DataDog/jsonapi/actions/workflows/test.yml)\n[![golangci-lint](https://github.com/DataDog/jsonapi/actions/workflows/lint.yml/badge.svg)](https://github.com/DataDog/jsonapi/actions/workflows/lint.yml)\n![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/DataDog/jsonapi)\n\njsonapi\n-----\n\nPackage jsonapi implements a marshaler/unmarshaler for [JSON:API v1.0](https://jsonapi.org/format/1.0).\n\n# Version\n\nThis package is in production use at [DataDog](https://www.datadoghq.com/) and should be considered stable and production ready.\n\nWe follow [semver](https://semver.org/) and are reserving the `v1.0.0` release until:\n\n- [JSON:API v1.1](https://jsonapi.org/format/1.1/) is released and we evaluate any breaking changes needed (unlikely)\n- Community adoption and feedback are evaluated\n- Continued internal use lets us gain more experience with the package\n\n# Quickstart\n\nTake a look at the [go reference](https://pkg.go.dev/github.com/DataDog/jsonapi) for more examples and detailed usage information.\n\n## Marshaling\n\n[jsonapi.Marshal](https://pkg.go.dev/github.com/DataDog/jsonapi#Marshal)\n\n```go\ntype Article struct {\n    ID    string `jsonapi:\"primary,articles\"`\n    Title string `jsonapi:\"attribute\" json:\"title\"`\n}\n\na := Article{ID: \"1\", Title:\"Hello World\"}\n\nb, err := jsonapi.Marshal(\u0026a)\nif err != nil {\n    // ...\n}\n\nfmt.Println(\"%s\", string(b))\n// {\n//     \"data\": {\n//         \"id\": \"1\",\n//         \"type\": \"articles\",\n//         \"attributes\": {\n//             \"title\": \"Hello World\"\n//         }\n//     }\n// }\n```\n\n## Unmarshaling\n\n[jsonapi.Unmarshal](https://pkg.go.dev/github.com/DataDog/jsonapi#Marshal)\n\n```go\nbody := `{\"data\":{\"id\":\"1\",\"type\":\"articles\",\"attributes\":{\"title\":\"Hello World\"}}}`\n\ntype Article struct {\n    ID    string `jsonapi:\"primary,articles\"`\n    Title string `jsonapi:\"attribute\" json:\"title\"`\n}\n\nvar a Article\nif err := jsonapi.Unmarshal([]byte(body), \u0026a); err != nil {\n    // ...\n}\n\nfmt.Prints(\"%s, %s\", a.ID, a.Title)\n// \"1\", \"Hello World\"\n```\n\n# Reference\n\nThe following information is well documented in the [go reference](https://pkg.go.dev/github.com/DataDog/jsonapi). This section is included for a high-level overview of the features available.\n\n## Struct Tags\n\nLike [encoding/json](https://pkg.go.dev/encoding/json) jsonapi is primarily controlled by the presence of a struct tag `jsonapi`. The standard `json` tag is still used for naming and `omitempty`.\n\n| Tag | Usage | Description | Alias |\n| --- | --- | --- | --- |\n| primary | `jsonapi:\"primary,{type},{omitempty}\"` | Defines the [identification](https://jsonapi.org/format/1.0/#document-resource-object-identification) field. Including omitempty allows for empty IDs (used for server-side id generation) | N/A |\n| attribute | `jsonapi:\"attribute\"` | Defines an [attribute](https://jsonapi.org/format/1.0/#document-resource-object-attributes). | attr |\n| relationship | `jsonapi:\"relationship\"` | Defines a [relationship](https://jsonapi.org/format/1.0/#document-resource-object-relationships). | rel |\n| meta | `jsonapi:\"meta\"` | Defines a [meta object](https://jsonapi.org/format/1.0/#document-meta). | N/A |\n\n## Functional Options\n\nBoth [jsonapi.Marshal](https://pkg.go.dev/github.com/DataDog/jsonapi#Marshal) and [jsonapi.Unmarshal](https://pkg.go.dev/github.com/DataDog/jsonapi#Unmarshal) take functional options.\n\n| Option | Supports |\n| --- | --- |\n| [jsonapi.MarshalOption](https://pkg.go.dev/github.com/DataDog/jsonapi#MarshalOption) | [meta](https://pkg.go.dev/github.com/DataDog/jsonapi#MarshalMeta), [json:api](https://pkg.go.dev/github.com/DataDog/jsonapi#MarshalJSONAPI), [includes](https://pkg.go.dev/github.com/DataDog/jsonapi#MarshalInclude), [document links](https://pkg.go.dev/github.com/DataDog/jsonapi#MarshalLinks), [sparse fieldsets](https://pkg.go.dev/github.com/DataDog/jsonapi#MarshalFields), [name validation](https://pkg.go.dev/github.com/DataDog/jsonapi#MarshalSetNameValidation) |\n| [jsonapi.UnmarshalOption](https://pkg.go.dev/github.com/DataDog/jsonapi#UnmarshalOption) | [meta](https://pkg.go.dev/github.com/DataDog/jsonapi#UnmarshalMeta), [document links](https://pkg.go.dev/github.com/DataDog/jsonapi#UnmarshalLinks), [name validation](https://pkg.go.dev/github.com/DataDog/jsonapi#UnmarshalSetNameValidation) |\n\n## Non-String Identifiers\n\n[Identification](https://jsonapi.org/format/1.0/#document-resource-object-identification) MUST be represented as a `string` regardless of the actual type in Go. To support non-string types for the primary field you can implement optional interfaces.\n\nYou can implement the following on the parent types (that contain non-string fields):\n\n| Context | Interface |\n| --- | --- |\n| Marshal | [jsonapi.MarshalIdentifier](https://pkg.go.dev/github.com/DataDog/jsonapi#MarshalIdentifier) |\n| Unmarshal | [jsonapi.UnmarshalIdentifier](https://pkg.go.dev/github.com/DataDog/jsonapi#UnmarshalIdentifier) |\n\nYou can implement the following on the field types themselves if they are not already implemented.\n\n| Context | Interface |\n| --- | --- |\n| Marshal | [fmt.Stringer](https://pkg.go.dev/fmt#Stringer) |\n| Marshal | [encoding.TextMarshaler](https://pkg.go.dev/encoding#TextMarshaler) |\n| Unmarshal | [encoding.TextUnmarshaler](https://pkg.go.dev/encoding#TextUnmarshaler) |\n\n### Order of Operations\n\n#### Marshaling\n\n1. Use MarshalIdentifier if it is implemented on the parent type\n2. Use the value directly if it is a string\n3. Use fmt.Stringer if it is implemented\n4. Use encoding.TextMarshaler if it is implemented\n5. Fail\n\n#### Unmarshaling\n\n1. Use UnmarshalIdentifier if it is implemented on the parent type\n2. Use encoding.TextUnmarshaler if it is implemented\n3. Use the value directly if it is a string\n4. Fail\n\n## Links\n\n[Links](https://jsonapi.org/format/1.0/#document-links) are supported via two interfaces and the [Link](https://pkg.go.dev/github.com/DataDog/jsonapi#Link) type. To include links you must implement one or both of the following interfaces.\n\n| Type | Interface |\n| --- | --- |\n| [Resource Object Link](https://jsonapi.org/format/1.0/#document-resource-object-links) | [Linkable](https://pkg.go.dev/github.com/DataDog/jsonapi#Linkable) |\n| [Resource Object Related Resource Link](https://jsonapi.org/format/1.0/#document-resource-object-related-resource-links) | [LinkableRelation](https://pkg.go.dev/github.com/DataDog/jsonapi#LinkableRelation) |\n\n# Alternatives\n\n## [google/jsonapi](https://github.com/google/jsonapi)\n\n- exposes an API that looks/feels a lot different than encoding/json\n- has quite a few bugs w/ complex types in attributes\n- doesn't provide easy access to top-level fields like meta\n- allows users to generate invalid JSON:API\n- not actively maintained\n\n## [manyminds/api2go/jsonapi](https://github.com/manyminds/api2go/tree/master/jsonapi)\n\n- has required interfaces\n- interfaces for includes/relationships are hard to understand and verbose to implement\n- allows users to generate invalid JSON:API\n- part of a broader api2go framework ecosystem\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatadog%2Fjsonapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatadog%2Fjsonapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatadog%2Fjsonapi/lists"}