{"id":17436078,"url":"https://github.com/rmordechay/jogson","last_synced_at":"2026-02-25T16:32:18.548Z","repository":{"id":257812159,"uuid":"868280622","full_name":"rmordechay/jogson","owner":"rmordechay","description":"Go library for working with JSON","archived":false,"fork":false,"pushed_at":"2024-10-17T22:35:44.000Z","size":174,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-16T04:13:33.522Z","etag":null,"topics":["golang","json"],"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/rmordechay.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":"2024-10-06T00:31:03.000Z","updated_at":"2025-03-04T01:15:57.000Z","dependencies_parsed_at":"2024-10-19T08:53:10.363Z","dependency_job_id":"18834524-b7f2-4783-8bf5-e62cf601e156","html_url":"https://github.com/rmordechay/jogson","commit_stats":null,"previous_names":["rmordechay/json-mapper","rmordechay/jsonmapper","rmordechay/jogson"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/rmordechay/jogson","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rmordechay%2Fjogson","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rmordechay%2Fjogson/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rmordechay%2Fjogson/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rmordechay%2Fjogson/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rmordechay","download_url":"https://codeload.github.com/rmordechay/jogson/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rmordechay%2Fjogson/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29830143,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-25T15:41:19.027Z","status":"ssl_error","status_checked_at":"2026-02-25T15:40:47.150Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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","json"],"created_at":"2024-10-17T10:02:03.012Z","updated_at":"2026-02-25T16:32:18.533Z","avatar_url":"https://github.com/rmordechay.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Jogson - JSON Mapper Library for Go\n\n![Go Version](https://img.shields.io/badge/go%20version-%3E=1.18-61CFDD.svg)\n[![GoDoc](https://pkg.go.dev/badge/badge)](https://pkg.go.dev/github.com/rmordechay/jogson)\n[![Go Report Card](https://goreportcard.com/badge/github.com/rmordechay/jogson)](https://goreportcard.com/report/github.com/rmordechay/jogson)\n\nA simple Go library to simplify working with JSON without the need to define structs.\n\n* [Installation](#installation)\n* [Create Object, Array or Mapper](#create-jsonobject-jsonarray-or-jsonmapper)\n* [Read from JSON](#read-from-json)\n    * [Scalars](#scalars)\n    * [Objects](#objects)\n    * [Arrays](#arrays)\n    * [Time](#time)\n    * [UUID](#uuid)\n    * [Types](#types)\n    * [Get JSON String](#get-json-string)\n* [Write to JSON](#write-to-JSON)\n    * [Write Object](#write-object)\n    * [Write Array](#write-array)\n* [Error Handling](#error-handling)\n* [Design](#design)\n  * [JsonMapper](#jsonmapper)\n  * [JsonObject](#jsonobject)\n  * [JsonArray](#jsonarray)\n\n## Installation\nJogson requires Go version `1.18` or above. \n\nTo install the library use:\n\n```bash\ngo get github.com/rmordechay/jogson\n```\n\n## Create JsonObject, JsonArray or JsonMapper\n\nFor more information, see [design](#Design).\n\n#### From String\n\n```go\nobject, err := jogson.NewObjectFromString(jsonString)\narray, err := jogson.NewArrayFromString(jsonString)\nmapper, err := jogson.NewMapperFromString(jsonString)\n```\n\n#### From Bytes\n\n```go\nobject, err := jogson.NewObjectFromBytes(jsonBytes)\narray, err := jogson.NewArrayFromBytes(jsonBytes)\nmapper, err := jogson.NewMapperFromBytes(jsonBytes)\n```\n\n#### From Struct\n\n```go\nobject, err := jogson.NewObjectFromStruct(jsonStruct)\narray, err := jogson.NewArrayFromStruct(jsonStruct)\nmapper, err := jogson.NewMapperFromStruct(jsonStruct)\n```\n\n#### From File\n\n```go\nmapper, err := jogson.NewMapperFromFile(jsonFilePath)\nobject, err := jogson.NewObjectFromFile(jsonFilePath)\narray, err := jogson.NewArrayFromFile(jsonFilePath)\n```\n\n## Read from JSON\n\nOnce you have an object, an array or a mapper, you can read the data easily. Consider the following JSON\n\n```go\njsonString := `{\n    \"id\": \"748494b8-7d6e-4cad-8065-89e758797313\",\n    \"name\": \"Jason\",\n    \"age\": 43,\n    \"height\": 1.87,\n    \"is_funny\": false,\n    \"address\": null,\n    \"birthday\": \"1981-10-08\",\n    \"features\": [\"tall\", \"blue eyes\", null],\n    \"children\": {\n        \"Rachel\": {\"age\": 15, \"is_funny\": false}, \n        \"Sara\":   {\"age\": 19, \"is_funny\": true}\n    }\n}`\n```\n\n### Scalars\n\nGetting scalars - `string`, `int`, etc. - is similar both for object and array and only differ\nin the parameter type (objects take `string` as key and arrays take `int` as index). You can get scalars by value or by reference, where the latter allows JSON null values. Nullable methods have\nthe suffix 'N' in their names.\n\n#### From Object\n\nBy value:\n\n```go\n// string \nvar name string = object.GetString(\"name\") // Jason\n\n// int \nvar age int = object.GetInt(\"age\") // 15\n\n// float64 \nvar height float64 = object.GetFloat(\"height\") // 1.87\n\n// bool \nvar isFunny bool = object.GetBool(\"is_funny\") // false\n```\n\nBy reference, which allows JSON null values (note the suffix 'N' at the end of the method names):\n\n```go\n// string\nvar nameNullable *string = object.GetStringN(\"non-existent-key\") // nil\n\n// int\nvar ageNullable *int = object.GetIntN(\"non-existent-key\") // nil\n\n// float64\nvar heightNullable *float64 = object.GetFloatN(\"non-existent-key\") // nil\n\n// bool\nvar isFunnyNullable *bool = object.GetBoolN(\"non-existent-key\") // nil\n```\n\n#### From Array\n\nBy value:\n\n```go\n// string \nvar s string = array.GetString(0)\n\n// int \nvar i int = array.GetInt(2)\n\n// float64 \nvar f float64 = array.GetFloat(5)\n\n// bool \nvar b bool = array.GetBool(7)\n```\n\nBy reference, which allows JSON null values (Note the suffix 'N' at the end of the method names):\n\n```go\n// string\nvar nameNullable *string = array.GetStringN(100) // nil\n\n// int\nvar ageNullable *int = array.GetIntN(100) // nil\n\n// float64\nvar heightNullable *float64 = array.GetFloatN(100) // nil\n\n// bool\nvar isFunnyNullable *bool = array.GetBoolN(100) // nil\n```\n\n\n### Objects\n\n```go\n// Check if a key exists\nvar keyExists bool = object.Contains(\"children\")\n\n// Check if the object is empty\nvar objectEmpty bool = object.IsEmpty()\n\n// Get the object's size\nvar objectLen int = object.Length()\n\n// Get object's keys\nvar keys []string = object.Keys()\n\n// Get object's values\nvalues := object.Values()\n\n// Iterating over an object with key, value pair\nchildren := object.GetObject(\"children\")\nfor key, child := range children.Elements() {\n    fmt.Println(\"Child name:\", key)                   // Rachel, Sara\n    fmt.Println(child.AsObject.GetInt(\"age\"))         // 15, 19\n    fmt.Println(child.AsObject.GetBool(\"is_funny\"))   // false, true\n}\n```\n\n#### As Maps\n\nYou can also get the object as a map of strings by scalars (`string`, `int`, etc.) Values that \nare JSON `null` will be returned as Go zero value. If you want to regard null values, call the \nfunction with the suffix `N` (see next section). If a null was found, `LastError` will be set\nand report a null conversion error. For more information, see [error handling](#error-handling).\n\n```go\n// Get the JsonObject as map of string and string\nvar stringMap map[string]string = object.AsStringMap()\n\n// Get the JsonObject as map of string and int\nvar intMap map[string]int = object.AsIntMap()\n\n// Get the JsonObject as map of string and float\nvar floatMap map[string]float64 = object.AsFloatMap()\n\n// Get as a slice of JsonArray\nvar nestedArray map[string]JsonArray = object.AsArrayMap()\n\n// Get as a slice of JsonObject\nvar objectArray map[string]JsonObject = object.AsObjectMap()\n```\n\n#### As Maps with Nullable Values\n\nIf the object contains null values, and you want to represent that as nil value instead of zero value, you can \nuse one of the following functions that returns a pointer rather than a value which allows nil. This set of methods \ndo not set the `LastError` when a null value was found but instead returns it without reporting an error. \n\nNote! This applies only for the scalar types. `JsonObject` and `JsonArray` will return an instance anyway,\nand you should use the `IsNull()` method to check if they are null.\n\n```go\n// Get the JsonObject as map of string and nullable strings\nvar nullableStringMap map[string]*string = object.AsStringMapN()\n\n// Get the JsonObject as map of string and nullable ints\nvar nullableIntMap map[string]*int = object.AsIntMapN()\n\n// Get the JsonObject as map of string and nullable floats\nvar nullableSloatMap map[string]*float64 = object.AsFloatMapN()\n```\n\n### Arrays\n\n```go\n// Get array from object\nfeatures := object.GetArray(\"features\")\n\n// Get features length\narrayLen := features.Length() // 2\n\n// Get an element of features by index\nsecondElement := features.Get(1)\n\n// Iterating over an array\nfor _, feature := range features.Elements() {\n    fmt.Println(feature.AsString) // tall, ...\n}\n```\n\n#### As Arrays\n\nYou can also get the array as a slice of scalars (`string`, `int`, etc.). Values that\nare JSON `null` will be returned as Go zero value. If you want to regard null values, call the\nfunction with the suffix `N` (see next section). If a null was found, `LastError` will be set\nand report a null conversion error. For more information, see [error handling](#error-handling).\n\n```go\n\n// Get the JsonArray as a slice of string\nvar stringArray []string = array.AsStringArray()\n\n// Get the JsonArray as a slice of int\nvar intArray []int = array.AsIntArray()\n\n// Get the JsonArray as a slice of float\nvar floatArray []float64 = array.AsFloatArray()\n\n// Get the JsonArray as a slice of JsonArray\nvar nestedArray []JsonArray = array.As2DArray()\n\n// Get the JsonArray as a slice of JsonObject\nvar objectArray []JsonObject = array.AsObjectArray()\n```\n\n#### As Arrays of Nullable Values\n\nIf the array contains null values, and you want to represent that as nil value instead of zero value, you can\nuse one of the following functions that returns a pointer rather than a value which allows nil. This set of methods\ndo not set the `LastError` when a null value was found but instead returns it without reporting an error.\n\nNote! This applies only for the scalar types. `JsonObject` and `JsonArray` will return an instance anyway, \nand you should use the `IsNull()` method to check if they are null.\n\n```go\n// Get the JsonArray as a slice of nullable strings\nvar nullableStringArray []*string = array.AsStringArrayN()\n\n// Get the JsonArray as a slice of nullable ints\nvar nullableIntArray []*int = array.AsIntArrayN()\n\n// Get the JsonArray as a slice of nullable floats\nvar nullableSloatArray []*float64 = array.AsFloatArrayN()\n```\n\n### Time\n\nTo get a string value as `time.Time`\n\n```go\nvar birthday time.Time = object.GetTime(\"birthday\") // 1981-10-08T00:00:00Z\nvar birthday time.Time = array.GetTime(0)\nvar birthday time.Time = mapper.AsTime()\n```\n\nThe mapper will try to format the string against different time formats to increase the chance of correct parsing. The following \nformats are supported:\n\n`time.RFC3339` `time.RFC850` `time.RFC822` `time.RFC822Z` `time.RFC1123` `time.RFC1123Z` `time.RFC3339Nano` `time.ANSIC` `time.UnixDate` `time.RubyDate` `time.Layout` `time.Kitchen` `time.Stamp` `time.StampMilli` `time.StampMicro` `time.StampNano` `time.DateTime` `time.DateOnly` `time.TimeOnly`\n\n\n### UUID\n\nYou can also get a string value as `uuid.UUID` type\n\n```go\nvar uuidValue uuid.UUID = object.GetUUID(\"id\")\nvar uuidValue uuid.UUID = array.GetUUID(0)\nvar uuidValue uuid.UUID = mapper.AsUUID()\n```\n\n### Types\n\nTo check what type is your `JsonMapper` currently holding, use\n\n```go\nfmt.Println(mapper.IsObject)    // true\nfmt.Println(mapper.IsBool)      // false\nfmt.Println(mapper.IsInt)       // false\nfmt.Println(mapper.IsFloat)     // false\nfmt.Println(mapper.IsString)    // false\nfmt.Println(mapper.IsArray)     // false\nfmt.Println(mapper.IsNull)      // false\n```\n\n### Get JSON String\n\nEvery JSON element - `JsonObject`, `JsonArray` or `JsonMapper` - have the method `String()` and `PrettyString()`. \nThe returned string from these methods will be a valid JSON. For example\n\n```go\nfmt.Println(mapper.AsObject.String())\n// output: {\"age\":43,\"children\":{\"Rachel\":{\"age\":15,\"is_funny\":false},\"Sara\":{\"age\":19,\"is_funny\":true}},\"features\":[\"tall\",\"blue eyes\"],\"is_funny\":false,\"name\":\"Jason\"}\n\nfmt.Println(mapper.AsObject.Get(\"children\").String())\n// output: {\"Rachel\":{\"age\":15,\"is_funny\":false},\"Sara\":{\"age\":19,\"is_funny\":true}}\n```\n\nor with `PrettyString()`\n\n```go\nfmt.Println(object.GetObject(\"children\").PrettyString())\n// output:\n// {\n//   \"address\": null,\n//   \"age\": 43,\n//   \"birthday\": \"1981-10-08\",\n//   \"children\": {\n//     \"Rachel\": {\n//       \"age\": 15,\n//       \"is_funny\": false\n//     },\n//     \"Sara\": {\n//       \"age\": 19,\n//       \"is_funny\": true\n//     }\n//   },\n//   \"features\": [\n//     \"tall\",\n//     \"blue eyes\",\n//     null\n//   ],\n//   \"height\": 1.87,\n//   \"is_funny\": false,\n//   \"name\": \"Jason\"\n// }\n```\n\n## Write to JSON\n\nTo write a JSON object or array is as simple as reading from it.\n\n### Write Object\n\n```go\n// Create a new object\nobj := jogson.NewObject()\nobj.AddKeyValue(\"name\", \"Chris\")\nfmt.Println(obj.String()) // {\"name\":\"Chris\"}\n```\n\n### Write Array\n\n```go\n// Create a new array\narr := jogson.NewArray()\narr.AddElement(15)\narr.AddElement(19)\nfmt.Println(arr.String()) // [15,19]\n```\n\n## Error Handling\nError handling is designed in such a way to not break the flow and to allow a cleaner code. In most cases\nerrors are not returned, but instead, they are stored in an exported field, `LastError`, which can be found in \nboth `JsonObject` and `JsonArray` and can be used to check for the type of error after an operation is made.\n\n```go\n_ = object.GetString(\"non-existent-key\")\nif object.LastError != nil {\n    fmt.Println(object.LastError) // output: key was not found: 'non-existent-key'\n}\n```\n\nNote, `LastError` is reset at the beginning of every operation, so if you need a reference to an old\nerror, you will have to store it in a variable. For example:\n\n```go\n_ = object.GetString(\"address\")\nfmt.Println(object.LastError) // output: type conversion error: \u003cnil\u003e could not be converted to string\n_ = object.GetString(\"name\")\nfmt.Println(object.LastError) // output: \u003cnil\u003e\n```\n\n## Design\n\nThere are 3 structs that are important to know when working with the library\n* `JsonMapper` struct for generic JSON.\n* `JsonObject` represents JSON object.\n* `JsonArray`  represents JSON array.\n\n#### JsonMapper\n\n`JsonMapper` is a struct that holds JSON data and serves as a generic type for all possible JSON types. It has `AsX` and `IsX` \nfields with which you can get the data and check the type, respectively. For example, if your data is a JSON object, \nyou can call `JsonMapper.AsObject`, or if it's a string, `JsonMapper.AsString`. This struct is best used when you don't \nknow the type at compile time and want to check it dynamically. In this case you can use `JsonMapper.IsArray`, \n`JsonMapper.IsString`, `JsonMapper.IsFloat`, etc. \n\nNote, in any case, `AsX` never returns nil, but always the zero value. If the underlying data is null, then `IsNull` will \nbe set to true. \n\n`JsonMapper` is also returned in cases where the return type can be any JSON type. For example, `JsonArray.Elements()` \nreturns a slice `[]JsonMapper` over which you can iterate or query specific elements. Other methods that return `JsonMapper` \n(instead of `JsonObject` or `JsonArray`) are `JsonObject.Values()`, `JsonObject.Get()`, `JsonArray.Get()`, `JsonArray.Find()` and more. \n\n#### JsonObject\n\n`JsonObject` holds JSON object data and has different methods to read from JSON object and write to it. Once you have an instance, \nyou can use the various methods to read or write data to you object. There are multiple ways to get a `JsonObject`. You can parse \nit directly, get it as an element of an array, or a value in a parent object.\n\nThere are 3 sets of methods that you can use when working with `JsonObject`.\n* `GetX(key string)`: gets a value in the object as the requested type. For example, GetString(\"key\") gets the value associated with `key` as type `string` \n* `AsXMap()`: gets the value as the requested type. For example, AsStringMap(\"key\") gets the value associated with `key` as type `map[string]string` \n* `AddX(key string, value X)`: adds `value`, associated with `key`, to the object as the requested type. For example, `AddString(\"key\", \"string_value\")` adds the string `string_value` associated with the `key`   \n\n#### JsonArray\n`JsonArray` is in many ways almost identical to `JsonObject`. It also contains the underlying array and methods to read and \nwrite data, and both also keep the same names for the methods. However, they have some minor differences. You can read more about them \nin the next section.\n\n#### `JsonObject` and `JsonArray` Similarities and Differences\nThe structs `JsonObject` and `JsonArray` have very similar methods, both in naming and semantics. For example, both structs\nhave `GetString()`, `GetInt()`, `GetFloat()`, `IsNull()`, `IsEmpty()` and other methods that are identical in names. Additionally, \nthey both have similar method names with the similar semantics. For example, `JsonObject.AsStringMap` will return `map[string]string`,\nwhereas `JsonArray.AsStringArray` will return `[]string`.\n\n\nAs a rule of thumb, they have 2 differences:\n  * **Input**:\n    * `JsonObject`'s methods mostly take a `string` as the key, e.g. `GetInt(\"age\")`.\n    * `JsonArray`'s methods mostly take an `int` as the index, e.g. `GetBool(1)`.\n  * **Output**:\n    * `JsonObject`'s methods mostly return a `map` or `JsonObject`, e.g. `GetFloatMap() -\u003e map[string]string`. \n    * `JsonArray`'s methods mostly return a `slice` or `JsonArray`, e.g. `GetFloatArray(1)  -\u003e []float`.\n\n#### Methods and Variables Prefix\nThe prefixes, `As`, `Is`, `Get` and `Add` have similar semantics across the library and can be found in `JsonMapper`, `JsonObject`\nand `JsonArray`.\n* `IsX`: checks for the value's type. For example `JsonMapper.IsBool`\n* `AsX`: converts the current data to other type representation. For example, `JsonArray.AsStringArray()` converts JsonArray to `[]string`.\n* `GetX`: Fetches the data, usually with some sort of search in the underlying data.\n* `AddX`: Adds the data to the JSON array or object\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frmordechay%2Fjogson","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frmordechay%2Fjogson","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frmordechay%2Fjogson/lists"}