{"id":13413275,"url":"https://github.com/Qntfy/kazaam","last_synced_at":"2025-03-14T19:31:42.981Z","repository":{"id":9909339,"uuid":"63700025","full_name":"qntfy/kazaam","owner":"qntfy","description":"Arbitrary transformations of JSON in Golang","archived":false,"fork":false,"pushed_at":"2022-06-06T06:01:18.000Z","size":1258,"stargazers_count":279,"open_issues_count":23,"forks_count":55,"subscribers_count":20,"default_branch":"master","last_synced_at":"2024-10-01T17:18:33.385Z","etag":null,"topics":["golang","json","json-data","json-format","jsonpath","transformations"],"latest_commit_sha":null,"homepage":null,"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/qntfy.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}},"created_at":"2016-07-19T14:19:03.000Z","updated_at":"2024-09-19T15:08:30.000Z","dependencies_parsed_at":"2022-07-24T20:32:25.490Z","dependency_job_id":null,"html_url":"https://github.com/qntfy/kazaam","commit_stats":null,"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qntfy%2Fkazaam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qntfy%2Fkazaam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qntfy%2Fkazaam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qntfy%2Fkazaam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qntfy","download_url":"https://codeload.github.com/qntfy/kazaam/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243635299,"owners_count":20322913,"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","json","json-data","json-format","jsonpath","transformations"],"created_at":"2024-07-30T20:01:36.643Z","updated_at":"2025-03-14T19:31:42.690Z","avatar_url":"https://github.com/qntfy.png","language":"Go","funding_links":[],"categories":["JSON","Utilities","實用工具","工具库","实用工具"],"sub_categories":["Search and Analytic Databases","HTTP Clients","Advanced Console UIs","SQL 查询语句构建库","高級控制台界面","交流","高级控制台界面","检索及分析资料库","\u003cspan id=\"高级控制台用户界面-advanced-console-uis\"\u003e高级控制台用户界面 Advanced Console UIs\u003c/span\u003e"],"readme":"# kazaam\n\n[![Travis Build Status](https://img.shields.io/travis/qntfy/kazaam.svg?branch=master)](https://travis-ci.com/qntfy/kazaam)\n[![Coverage Status](https://coveralls.io/repos/github/qntfy/kazaam/badge.svg?branch=master)](https://coveralls.io/github/qntfy/kazaam?branch=master)\n[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![GitHub release](https://img.shields.io/github/release/qntfy/kazaam.svg?maxAge=3600)](https://github.com/qntfy/kazaam/releases/latest)\n[![Go Report Card](https://goreportcard.com/badge/github.com/qntfy/kazaam)](https://goreportcard.com/report/github.com/qntfy/kazaam)\n[![GoDoc](https://godoc.org/github.com/qntfy/kazaam?status.svg)](https://pkg.go.dev/github.com/qntfy/kazaam/v4)\n\n## Description\n\nKazaam was created with the goal of supporting easy and fast transformations of JSON data with Golang.\nThis functionality provides us with an easy mechanism for taking intermediate JSON message representations\nand transforming them to formats required by arbitrary third-party APIs.\n\nInspired by [Jolt](https://github.com/bazaarvoice/jolt), Kazaam supports JSON to JSON transformation via a\ntransform \"specification\" also defined in JSON. A specification is comprised of one or more \"operations\". See\nSpecification Support, below, for more details.\n\n## Documentation\n\nAPI Documentation is available on [pkg.go.dev](https://pkg.go.dev/github.com/qntfy/kazaam/v4).\n\n## Features\n\nKazaam is primarily designed to be used as a library for transforming arbitrary JSON.\nIt ships with six built-in transform types, described below, which provide significant flexibility\nin reshaping JSON data.\n\nAlso included when you `go get` Kazaam, is a binary implementation, `kazaam` that can be used for\ndevelopment and testing of new transform specifications.\n\nFinally, Kazaam supports the implementation of custom transform types. We encourage and appreciate\npull requests for new transform types so that they can be incorporated into the Kazaam distribution,\nbut understand sometimes time-constraints or licensing issues prevent this. See the API documentation\nfor details on how to write and register custom transforms.\n\nDue to performance considerations, Kazaam does not fully validate that input data is valid JSON. The\n`IsJson()` function is provided for convenience if this functionality is needed, it may significantly slow\ndown use of Kazaam.\n\n## Specification Support\n\nKazaam currently supports the following transforms:\n\n- shift\n- concat\n- coalesce\n- extract\n- timestamp\n- uuid\n- default\n- pass\n- delete\n\n### Shift\n\nThe shift transform is the current Kazaam workhorse used for remapping of fields.\nThe specification supports jsonpath-esque JSON accesses and sets. Concretely\n\n```javascript\n{\n  \"operation\": \"shift\",\n  \"spec\": {\n    \"object.id\": \"doc.uid\",\n    \"gid2\": \"doc.guid[1]\",\n    \"allGuids\": \"doc.guidObjects[*].id\"\n  }\n}\n```\n\nexecuted on a JSON message with format\n\n```javascript\n{\n  \"doc\": {\n    \"uid\": 12345,\n    \"guid\": [\"guid0\", \"guid2\", \"guid4\"],\n    \"guidObjects\": [{\"id\": \"guid0\"}, {\"id\": \"guid2\"}, {\"id\": \"guid4\"}]\n  },\n  \"top-level-key\": null\n}\n```\n\nwould result in\n\n```javascript\n{\n  \"object\": {\n    \"id\": 12345\n  },\n  \"gid2\": \"guid2\",\n  \"allGuids\": [\"guid0\", \"guid2\", \"guid4\"]\n}\n```\n\nThe jsonpath implementation supports a few special cases:\n\n- *Array accesses*: Retrieve `n`th element from array\n- *Array wildcarding*: indexing an array with `[*]` will return every matching element in an array\n- *Top-level object capture*: Mapping `$` into a field will nest the entire original object under the requested key\n- *Array append/prepend and set*: Append and prepend an array with `[+]` and `[-]`. Attempting to write an array element that does not exist results in null padding as needed to add that element at the specified index (useful with `\"inplace\"`).\n\nThe shift transform also supports a `\"require\"` field. When set to `true`,\nKazaam will throw an error if *any* of the paths in the source JSON are not\npresent.\n\nFinally, shift by default is destructive. For in-place operation, an optional `\"inplace\"`\nfield may be set.\n\n### Concat\n\nThe concat transform allows the combination of fields and literal strings into a single string value.\n\n```javascript\n{\n    \"operation\": \"concat\",\n    \"spec\": {\n        \"sources\": [{\n            \"value\": \"TEST\"\n        }, {\n            \"path\": \"a.timestamp\"\n        }],\n        \"targetPath\": \"a.timestamp\",\n        \"delim\": \",\"\n    }\n}\n```\n\nexecuted on a JSON message with format\n\n```javascript\n{\n    \"a\": {\n        \"timestamp\": 1481305274\n    }\n}\n```\n\nwould result in\n\n```javascript\n{\n    \"a\": {\n        \"timestamp\": \"TEST,1481305274\"\n    }\n}\n```\n\nNotes:\n\n- *sources*: list of items to combine (in the order listed)\n  - literal values are specified via `value`\n  - field values are specified via `path` (supports the same addressing as `shift`)\n- *targetPath*: where to place the resulting string\n  - if this an existing path, the result will replace current value.\n- *delim*: Optional delimiter\n\nThe concat transform also supports a `\"require\"` field. When set to `true`,\nKazaam will throw an error if *any* of the paths in the source JSON are not\npresent.\n\n### Coalesce\n\nA coalesce transform provides the ability to check multiple possible keys to find a desired value. The first matching key found of those provided is returned.\n\n```javascript\n{\n  \"operation\": \"coalesce\",\n  \"spec\": {\n    \"firstObjectId\": [\"doc.guidObjects[0].uid\", \"doc.guidObjects[0].id\"]\n  }\n}\n```\n\nexecuted on a json message with format\n\n```javascript\n{\n  \"doc\": {\n    \"uid\": 12345,\n    \"guid\": [\"guid0\", \"guid2\", \"guid4\"],\n    \"guidObjects\": [{\"id\": \"guid0\"}, {\"id\": \"guid2\"}, {\"id\": \"guid4\"}]\n  }\n}\n```\n\nwould result in\n\n```javascript\n{\n  \"doc\": {\n    \"uid\": 12345,\n    \"guid\": [\"guid0\", \"guid2\", \"guid4\"],\n    \"guidObjects\": [{\"id\": \"guid0\"}, {\"id\": \"guid2\"}, {\"id\": \"guid4\"}]\n  },\n  \"firstObjectId\": \"guid0\"\n}\n```\n\nCoalesce also supports an `ignore` array in the spec. If an otherwise matching key has a value in `ignore`, it is not considered a match.\nThis is useful e.g. for empty strings\n\n```javascript\n{\n  \"operation\": \"coalesce\",\n  \"spec\": {\n    \"ignore\": [\"\"],\n    \"firstObjectId\": [\"doc.guidObjects[0].uid\", \"doc.guidObjects[0].id\"]\n  }\n}\n```\n\n### Extract\n\nAn `extract` transform provides the ability to select a sub-object and have kazaam return that sub-object as the top-level object. For example\n\n```javascript\n{\n  \"operation\": \"extract\",\n  \"spec\": {\n    \"path\": \"doc.guidObjects[0].path.to.subobject\"\n  }\n}\n```\n\nexecuted on a json message with format\n\n```javascript\n{\n  \"doc\": {\n    \"uid\": 12345,\n    \"guid\": [\"guid0\", \"guid2\", \"guid4\"],\n    \"guidObjects\": [{\"path\": {\"to\": {\"subobject\": {\"name\": \"the.subobject\", \"field\", \"field.in.subobject\"}}}}, {\"id\": \"guid2\"}, {\"id\": \"guid4\"}]\n  }\n}\n```\n\nwould result in\n\n```javascript\n{\n  \"name\": \"the.subobject\",\n  \"field\": \"field.in.subobject\"\n}\n```\n\n### Timestamp\n\nA `timestamp` transform parses and formats time strings using the golang\nsyntax. **Note**: this operation is done in-place. If you want to preserve the\noriginal string(s), pair the transform with `shift`. This transform also\nsupports the `$now` operator for `inputFormat`, which will set the current\ntimestamp at the specified path, formatted according to the `outputFormat`.\n`$unix` is supported for both input and output formats as a Unix time, the\nnumber of seconds elapsed since January 1, 1970 UTC as an integer string.\n\n```javascript\n{\n  \"operation\": \"timestamp\",\n  \"timestamp[0]\": {\n    \"inputFormat\": \"Mon Jan _2 15:04:05 -0700 2006\",\n    \"outputFormat\": \"2006-01-02T15:04:05-0700\"\n  },\n  \"nowTimestamp\": {\n    \"inputFormat\": \"$now\",\n    \"outputFormat\": \"2006-01-02T15:04:05-0700\"\n  },\n  \"epochTimestamp\": {\n    \"inputFormat\": \"2006-01-02T15:04:05-0700\",\n    \"outputFormat\": \"$unix\"\n  }\n}\n\n```\n\nexecuted on a json message with format\n\n```javascript\n{\n  \"timestamp\": [\n    \"Sat Jul 22 08:15:27 +0000 2017\",\n    \"Sun Jul 23 08:15:27 +0000 2017\",\n    \"Mon Jul 24 08:15:27 +0000 2017\"\n  ]\n}\n```\n\nwould result in\n\n```javascript\n{\n  \"timestamp\": [\n    \"2017-07-22T08:15:27+0000\",\n    \"Sun Jul 23 08:15:27 +0000 2017\",\n    \"Mon Jul 24 08:15:27 +0000 2017\"\n  ]\n  \"nowTimestamp\": \"2017-09-08T19:15:27+0000\"\n}\n```\n\n### UUID\n\nA `uuid` transform generates a UUID based on the spec. Currently supports UUIDv3, UUIDv4, UUIDv5.\n\nFor version 4 is a very simple spec\n\n```javascript\n{\n    \"operation\": \"uuid\",\n    \"spec\": {\n        \"doc.uuid\": {\n            \"version\": 4, //required\n        }\n    }\n}\n```\n\nexecuted on a json message with format\n\n```javascript\n{\n  \"doc\": {\n    \"author_id\": 11122112,\n    \"document_id\": 223323,\n    \"meta\": {\n      \"id\": 23\n    }\n  }\n}\n```\n\nwould result in\n\n```javascript\n{\n  \"doc\": {\n    \"author_id\": 11122112,\n    \"document_id\": 223323,\n    \"meta\": {\n      \"id\": 23\n    }\n    \"uuid\": \"f03bacc1-f4e0-4371-a5c5-e8160d3d6c0c\"\n  }\n}\n```\n\nFor UUIDv3 \u0026 UUIDV5 are a bit more complex. These require a Name Space which is a valid UUID already, and a set of paths, which generate UUID's based on the value of that path. If that path doesn't exist in the incoming document, a default field will be used instead. **Note** both of these fields must be strings.\n**Additionally** you can use the 4 predefined namespaces such as `DNS`, `URL`, `OID`, \u0026 `X500` in the name space field otherwise pass your own UUID.\n\n```javascript\n{\n   \"operation\":\"uuid\",\n   \"spec\":{\n      \"doc.uuid\":{\n         \"version\":5,\n         \"namespace\":\"DNS\",\n         \"names\":[\n            {\"path\":\"doc.author_name\", \"default\":\"some string\"},\n            {\"path\":\"doc.type\", \"default\":\"another string\"},\n         ]\n      }\n   }\n}\n```\n\nexecuted on a json message with format\n\n```javascript\n{\n  \"doc\": {\n    \"author_name\": \"jason\",\n    \"type\": \"secret-document\"\n    \"document_id\": 223323,\n    \"meta\": {\n      \"id\": 23\n    }\n  }\n}\n```\n\nwould result in\n\n```javascript\n{\n  \"doc\": {\n    \"author_name\": \"jason\",\n    \"type\": \"secret-document\",\n    \"document_id\": 223323,\n    \"meta\": {\n      \"id\": 23\n    },\n    \"uuid\": \"f03bacc1-f4e0-4371-a7c5-e8160d3d6c0c\"\n  }\n}\n```\n\n### Default\n\nA default transform provides the ability to set a key's value explicitly. For example\n\n```javascript\n{\n  \"operation\": \"default\",\n  \"spec\": {\n    \"type\": \"message\"\n  }\n}\n```\n\nwould ensure that the output JSON message includes `{\"type\": \"message\"}`.\n\n### Delete\n\nA delete transform provides the ability to delete keys in place.\n\n```javascript\n{\n  \"operation\": \"delete\",\n  \"spec\": {\n    \"paths\": [\"doc.uid\", \"doc.guidObjects[1]\"]\n  }\n}\n```\n\nexecuted on a json message with format\n\n```javascript\n{\n  \"doc\": {\n    \"uid\": 12345,\n    \"guid\": [\"guid0\", \"guid2\", \"guid4\"],\n    \"guidObjects\": [{\"id\": \"guid0\"}, {\"id\": \"guid2\"}, {\"id\": \"guid4\"}]\n  }\n}\n```\n\nwould result in\n\n```javascript\n{\n  \"doc\": {\n    \"guid\": [\"guid0\", \"guid2\", \"guid4\"],\n    \"guidObjects\": [{\"id\": \"guid0\"}, {\"id\": \"guid4\"}]\n  }\n}\n```\n\n### Pass\n\nA pass transform, as the name implies, passes the input data unchanged to the output. This is used internally\nwhen a null transform spec is specified, but may also be useful for testing.\n\n## Usage\n\nTo start, go get the versioned repository:\n\n```sh\ngo get gopkg.in/qntfy/kazaam.v3\n```\n\n### Using as an executable program\n\nIf you want to create an executable binary from this project, follow\nthese steps (you'll need `go` installed and `$GOPATH` set):\n\n``` shell\ngo get gopkg.in/qntfy/kazaam.v3\ncd $GOPATH/src/gopkg.in/qntfy/kazaam.v3/kazaam\ngo install\n```\n\nThis will create an executable in `$GOPATH/bin` like you\nwould expect from the normal `go` build behavior.\n\n### Examples\n\nSee [godoc examples](https://godoc.org/pkg/gopkg.in/qntfy/kazaam.v3/#pkg-examples).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FQntfy%2Fkazaam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FQntfy%2Fkazaam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FQntfy%2Fkazaam/lists"}