{"id":25238600,"url":"https://github.com/jorgebay/jsonnav","last_synced_at":"2025-07-04T22:34:58.386Z","repository":{"id":276782643,"uuid":"929992405","full_name":"jorgebay/jsonnav","owner":"jorgebay","description":"Go package for accessing, navigating and manipulating values from an untyped json document.","archived":false,"fork":false,"pushed_at":"2025-03-11T14:10:21.000Z","size":30,"stargazers_count":22,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-26T09:37:32.537Z","etag":null,"topics":["go","go-library","golang","json","path"],"latest_commit_sha":null,"homepage":"","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/jorgebay.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,"zenodo":null}},"created_at":"2025-02-09T21:21:01.000Z","updated_at":"2025-03-11T14:10:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"a0d1b7a2-f1d2-45c1-94ef-7f3b544f04d8","html_url":"https://github.com/jorgebay/jsonnav","commit_stats":null,"previous_names":["jorgebay/jsonnav"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/jorgebay/jsonnav","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jorgebay%2Fjsonnav","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jorgebay%2Fjsonnav/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jorgebay%2Fjsonnav/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jorgebay%2Fjsonnav/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jorgebay","download_url":"https://codeload.github.com/jorgebay/jsonnav/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jorgebay%2Fjsonnav/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263628234,"owners_count":23490935,"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":["go","go-library","golang","json","path"],"created_at":"2025-02-11T17:52:21.642Z","updated_at":"2025-07-04T22:34:58.377Z","avatar_url":"https://github.com/jorgebay.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JSONNAV\n\njsonnav is a [Go package](https://pkg.go.dev/github.com/jorgebay/jsonnav#section-documentation) for accessing,\nnavigating and manipulating values from an untyped json document.\n\n[![Build](https://github.com/jorgebay/jsonnav/actions/workflows/test.yml/badge.svg)](https://github.com/jorgebay/jsonnav/actions/workflows/test.yml)\n\n## Features\n\n- Retrieve values from deeply nested json documents safely.\n- Built-in type check functions and conversions.\n- Iterate over arrays and objects.\n- Supports [GJSON][gjson] syntax for navigating the json document.\n- Set or delete values in place.\n\n## Installing\n\n```shell\ngo get github.com/jorgebay/jsonnav\n```\n\n## Usage\n\n```go\nv, err := jsonnav.Unmarshal(`{\"name\":{\"first\":\"Jimi\",\"last\":\"Hendrix\"},\"age\":27}`)\nv.Get(\"name\").Get(\"first\").String() // \"Jimi\"\nv.Get(\"name.last\").String() // \"Hendrix\"\nv.Get(\"age\").Float() // 27.0\nv.Get(\"path\").Get(\"does\").Get(\"not\").Get(\"exist\").Exists() // false\nv.Get(\"path.does.not.exist\").Exists() // false\n```\n\nIt uses [GJSON syntax][gjson] for navigating the json document.\n\n### Accessing values that may not exist\n\nIt's safe to access values that may not exist. The library will return a scalar `Value` representation\nwith `nil` underlying value.\n\n```go\nv, err := jsonnav.Unmarshal(`{\n    \"name\": {\"first\": \"Jimi\", \"last\": \"Hendrix\"},\n    \"instruments\": [{\"name\": \"guitar\"}]\n}`)\nv.Get(\"birth\").Get(\"date\").Exists() // false\nv.Get(\"birth.date\").Exists() // false\nv.Get(\"instruments\").Array().At(0).Get(\"name\").String() // \"guitar\"\nv.Get(\"instruments.0.name\").String() // \"guitar\"\nv.Get(\"instruments\").Array().At(1).Get(\"name\").String() // \"\"\nv.Get(\"instruments.1.name\").String() // \"\"\n```\n\n### Setting and deleting values\n\nYou can set or delete values in place using `Set()` and `Delete()` methods.\n\n```go\nv, err := jsonnav.Unmarshal(`{\"name\":{\"first\":\"Jimi\",\"last\":\"Hendrix\"},\"age\":27}`)\nv.Get(\"name\").Set(\"middle\", \"Marshall\")\nv.Set(\"birth.date\", \"1942-11-27\")\nv.Delete(\"age\")\n\nv.Get(\"birth\").Get(\"date\").String()  // \"1942-11-27\"\nv.Get(\"name\").Get(\"middle\").String() // \"Marshall\"\n```\n\n### Type checks and conversions\n\nThe library provides built-in functions for type checks and conversions that are safely free of errors and panics.\n\n#### Type check functions\n\n```go\nv, err := jsonnav.Unmarshal(`{\"name\":\"Jimi\",\"age\":27}`)\nv.Get(\"name\").IsString()     // true\nv.Get(\"age\").IsFloat()       // true\nv.Get(\"age\").IsBool()        // false\nv.Get(\"age\").IsObject()      // false\nv.Get(\"age\").IsArray()       // false\nv.Get(\"not_found\").IsNull()  // true\nv.Get(\"not_found\").IsEmpty() // true\n```\n\n#### Typed getters\n\n```go\nv, err := jsonnav.Unmarshal(`{\n    \"name\": \"Jimi\",\n    \"age\": 27,\n    \"instruments\": [\"guitar\"],\n    \"hall_of_fame\": true\n}`)\nv.Get(\"name\").String()       // \"Jimi\"\nv.Get(\"age\").Float()         // 27.0\nv.Get(\"hall_of_fame\").Bool() // true\nv.Get(\"instruments\").Array() // a slice of 1 Value with underlying value \"guitar\"\n```\n\nWhen the value doesn't match the expected type or it does not exist, it will default to a zero value of the\nexpected type and do conversions for scalars.\n\n- `String()` returns the string representation of float and bool values, otherwise an empty string.\n- `Float()` returns the float representation of string values, for other types it returns 0.0.\n- `Bool()` returns the bool representation of string values, for other types it returns false.\n- `Array()` returns an empty slice for non-array values.\n\n### Iterating over arrays\n\nYou can iterate over arrays using the `Array()` method.\n\n```go\nv, err := jsonnav.Unmarshal(`{\n    \"instruments\": [\n        {\"name\": \"guitar\"},\n        {\"name\": \"bass\"}\n    ]\n}`)\n\nfor _, instrument := range v.Get(\"instruments\").Array() {\n    fmt.Println(instrument.Get(\"name\").String())\n}\n```\n\nYou can also collect internal properties of an array using `#` gjson wildcard.\n\n```go\nfor _, instrumentName := range v.Get(\"instruments.#.name\").Array() {\n    fmt.Println(instrumentName.String())\n}\n```\n\n### Parsing\n\nThe library uses Golang built-in json marshallers. In case you want to use a custom marshaller, you can use\n`jsonnav.From[T]()` or `jsonnav.FromAny()` by providing the actual value.\n\n```go\nv, err := jsonnav.From(map[string]any{\"name\": \"John\", \"age\": 30})\nv.Get(\"name\").String() // \"John\"\n```\n\n## License\n\njsonnav is distributed under [MIT License](https://opensource.org/license/MIT).\n\n[gjson]: https://github.com/tidwall/gjson/blob/master/SYNTAX.md","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjorgebay%2Fjsonnav","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjorgebay%2Fjsonnav","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjorgebay%2Fjsonnav/lists"}