You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Kazaam was created with the goal of supporting easy and fast transformations of JSON data with Golang.
12
13
This functionality provides us with an easy mechanism for taking intermediate JSON message representations
13
14
and transforming them to formats required by arbitrary third-party APIs.
@@ -17,9 +18,11 @@ transform "specification" also defined in JSON. A specification is comprised of
17
18
Specification Support, below, for more details.
18
19
19
20
## Documentation
20
-
API Documentation is available at http://godoc.org/gopkg.in/qntfy/kazaam.v3.
21
+
22
+
API Documentation is available on [pkg.go.dev](https://pkg.go.dev/github.com/qntfy/kazaam/v4).
21
23
22
24
## Features
25
+
23
26
Kazaam is primarily designed to be used as a library for transforming arbitrary JSON.
24
27
It ships with six built-in transform types, described below, which provide significant flexibility
25
28
in reshaping JSON data.
@@ -37,7 +40,9 @@ Due to performance considerations, Kazaam does not fully validate that input dat
37
40
down use of Kazaam.
38
41
39
42
## Specification Support
43
+
40
44
Kazaam currently supports the following transforms:
45
+
41
46
- shift
42
47
- concat
43
48
- coalesce
@@ -49,8 +54,10 @@ Kazaam currently supports the following transforms:
49
54
- delete
50
55
51
56
### Shift
57
+
52
58
The shift transform is the current Kazaam workhorse used for remapping of fields.
53
59
The specification supports jsonpath-esque JSON accesses and sets. Concretely
60
+
54
61
```javascript
55
62
{
56
63
"operation":"shift",
@@ -63,6 +70,7 @@ The specification supports jsonpath-esque JSON accesses and sets. Concretely
63
70
```
64
71
65
72
executed on a JSON message with format
73
+
66
74
```javascript
67
75
{
68
76
"doc": {
@@ -75,6 +83,7 @@ executed on a JSON message with format
75
83
```
76
84
77
85
would result in
86
+
78
87
```javascript
79
88
{
80
89
"object": {
@@ -86,6 +95,7 @@ would result in
86
95
```
87
96
88
97
The jsonpath implementation supports a few special cases:
98
+
89
99
-*Array accesses*: Retrieve `n`th element from array
90
100
-*Array wildcarding*: indexing an array with `[*]` will return every matching element in an array
91
101
-*Top-level object capture*: Mapping `$` into a field will nest the entire original object under the requested key
@@ -99,7 +109,9 @@ Finally, shift by default is destructive. For in-place operation, an optional `"
99
109
field may be set.
100
110
101
111
### Concat
112
+
102
113
The concat transform allows the combination of fields and literal strings into a single string value.
114
+
103
115
```javascript
104
116
{
105
117
"operation":"concat",
@@ -116,6 +128,7 @@ The concat transform allows the combination of fields and literal strings into a
116
128
```
117
129
118
130
executed on a JSON message with format
131
+
119
132
```javascript
120
133
{
121
134
"a": {
@@ -125,6 +138,7 @@ executed on a JSON message with format
125
138
```
126
139
127
140
would result in
141
+
128
142
```javascript
129
143
{
130
144
"a": {
@@ -134,6 +148,7 @@ would result in
134
148
```
135
149
136
150
Notes:
151
+
137
152
-*sources*: list of items to combine (in the order listed)
138
153
- literal values are specified via `value`
139
154
- field values are specified via `path` (supports the same addressing as `shift`)
@@ -146,7 +161,9 @@ Kazaam will throw an error if *any* of the paths in the source JSON are not
146
161
present.
147
162
148
163
### Coalesce
164
+
149
165
A 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.
166
+
150
167
```javascript
151
168
{
152
169
"operation":"coalesce",
@@ -157,6 +174,7 @@ A coalesce transform provides the ability to check multiple possible keys to fin
157
174
```
158
175
159
176
executed on a json message with format
177
+
160
178
```javascript
161
179
{
162
180
"doc": {
@@ -168,6 +186,7 @@ executed on a json message with format
168
186
```
169
187
170
188
would result in
189
+
171
190
```javascript
172
191
{
173
192
"doc": {
@@ -181,6 +200,7 @@ would result in
181
200
182
201
Coalesce also supports an `ignore` array in the spec. If an otherwise matching key has a value in `ignore`, it is not considered a match.
183
202
This is useful e.g. for empty strings
203
+
184
204
```javascript
185
205
{
186
206
"operation":"coalesce",
@@ -192,7 +212,9 @@ This is useful e.g. for empty strings
192
212
```
193
213
194
214
### Extract
215
+
195
216
An `extract` transform provides the ability to select a sub-object and have kazaam return that sub-object as the top-level object. For example
217
+
196
218
```javascript
197
219
{
198
220
"operation":"extract",
@@ -203,6 +225,7 @@ An `extract` transform provides the ability to select a sub-object and have kaza
203
225
```
204
226
205
227
executed on a json message with format
228
+
206
229
```javascript
207
230
{
208
231
"doc": {
@@ -214,6 +237,7 @@ executed on a json message with format
214
237
```
215
238
216
239
would result in
240
+
217
241
```javascript
218
242
{
219
243
"name":"the.subobject",
@@ -222,13 +246,15 @@ would result in
222
246
```
223
247
224
248
### Timestamp
249
+
225
250
A `timestamp` transform parses and formats time strings using the golang
226
251
syntax. **Note**: this operation is done in-place. If you want to preserve the
227
-
original string(s), pair the transform with `shift`. This transform also
228
-
supports the `$now` operator for `inputFormat`, which will set the current
252
+
original string(s), pair the transform with `shift`. This transform also
253
+
supports the `$now` operator for `inputFormat`, which will set the current
229
254
timestamp at the specified path, formatted according to the `outputFormat`.
230
255
`$unix` is supported for both input and output formats as a Unix time, the
231
256
number of seconds elapsed since January 1, 1970 UTC as an integer string.
257
+
232
258
```javascript
233
259
{
234
260
"operation":"timestamp",
@@ -249,6 +275,7 @@ number of seconds elapsed since January 1, 1970 UTC as an integer string.
249
275
```
250
276
251
277
executed on a json message with format
278
+
252
279
```javascript
253
280
{
254
281
"timestamp": [
@@ -260,6 +287,7 @@ executed on a json message with format
260
287
```
261
288
262
289
would result in
290
+
263
291
```javascript
264
292
{
265
293
"timestamp": [
@@ -272,6 +300,7 @@ would result in
272
300
```
273
301
274
302
### UUID
303
+
275
304
A `uuid` transform generates a UUID based on the spec. Currently supports UUIDv3, UUIDv4, UUIDv5.
276
305
277
306
For version 4 is a very simple spec
@@ -288,6 +317,7 @@ For version 4 is a very simple spec
288
317
```
289
318
290
319
executed on a json message with format
320
+
291
321
```javascript
292
322
{
293
323
"doc": {
@@ -301,6 +331,7 @@ executed on a json message with format
301
331
```
302
332
303
333
would result in
334
+
304
335
```javascript
305
336
{
306
337
"doc": {
@@ -334,6 +365,7 @@ For UUIDv3 & UUIDV5 are a bit more complex. These require a Name Space which is
334
365
```
335
366
336
367
executed on a json message with format
368
+
337
369
```javascript
338
370
{
339
371
"doc": {
@@ -348,6 +380,7 @@ executed on a json message with format
348
380
```
349
381
350
382
would result in
383
+
351
384
```javascript
352
385
{
353
386
"doc": {
@@ -362,9 +395,10 @@ would result in
362
395
}
363
396
```
364
397
365
-
366
398
### Default
399
+
367
400
A default transform provides the ability to set a key's value explicitly. For example
401
+
368
402
```javascript
369
403
{
370
404
"operation":"default",
@@ -373,11 +407,13 @@ A default transform provides the ability to set a key's value explicitly. For ex
373
407
}
374
408
}
375
409
```
376
-
would ensure that the output JSON message includes `{"type": "message"}`.
377
410
411
+
would ensure that the output JSON message includes `{"type": "message"}`.
378
412
379
413
### Delete
414
+
380
415
A delete transform provides the ability to delete keys in place.
416
+
381
417
```javascript
382
418
{
383
419
"operation":"delete",
@@ -388,6 +424,7 @@ A delete transform provides the ability to delete keys in place.
388
424
```
389
425
390
426
executed on a json message with format
427
+
391
428
```javascript
392
429
{
393
430
"doc": {
@@ -399,6 +436,7 @@ executed on a json message with format
399
436
```
400
437
401
438
would result in
439
+
402
440
```javascript
403
441
{
404
442
"doc": {
@@ -408,14 +446,15 @@ would result in
408
446
}
409
447
```
410
448
411
-
412
449
### Pass
450
+
413
451
A pass transform, as the name implies, passes the input data unchanged to the output. This is used internally
414
452
when a null transform spec is specified, but may also be useful for testing.
0 commit comments