Merge pull request #101 from jmespath-community/jep/object-manipulation-functions

JEP-013 Object Manipulation Functions

Author: springcomp

function_schema.yml

@@ -3,6 +3,37 @@ $schema: https://json-schema.org/draft/2020-12/schema
 $id: https://jmespath.site/function_schema.yml
 title: JMESPath function
 description: JMESPath function definition and tests
+$defs:
+  unnamed_arg: &unnamed_arg
+    type: object
+    properties:
+      type: &type
+        description: ""
+        oneOf:
+          - enum: &types
+            - any
+            - number
+            - string
+            - boolean
+            - array
+            - object
+            - "null"
+            - expression
+            - "array[number]"
+            - "array[string]"
+            - "array[boolean]"
+            - "array[object]"
+            - "array[any]"
+            - "array[array[any]]"
+            - expression->any
+            - expression->number
+            - expression->string
+          - type: array
+            items:
+              enum: *types
+      desc:
+        type: string
+        description: ""
 type: object
 required: [name, topic, args, returns, desc, examples]
 properties:
@@ -20,24 +51,19 @@ properties:
         type: array
         description: ""
         items:
-          type: object
+          allOf:
+            - $ref: "#/$defs/unnamed_arg"
+            - type: object
+              required:
+              - name
+              properties:
+                name:
+                  type: string
+                  description: ""
           description: ""
-          additionalProperties: false
-          properties:
-            name:
-              type: string
-              description: ""
-            type: &type
-              description: ""
-              oneOf:
-                - enum: &types [any, number, string, boolean, array, object, "null", expression, "array[number]", "array[string]", "array[boolean]", "array[object]", "array[any]", "expression->any", "expression->number", "expression->string"]
-                - type: array
-                  items:
-                    enum: *types
-            desc:
-              type: string
-              description: ""
+          unevaluatedProperties: false
       optional: *arg
+      variadic: *unnamed_arg
   returns:
     type: object
     description: ""

functions/from_items.yml

@@ -0,0 +1,23 @@
+name: from_items
+topic: misc
+args:
+  required:
+  - name: arg
+    type: ['array[any]']
+    desc: ''
+  optional: []
+returns:
+  type: [object]
+  desc: ''
+desc: |2
+  Returns an object from the provided array of key value pairs.
+  This function is the inversed of the `items()` function.
+examples:
+  from_items:
+    context: [["one", 1], ["two", 2]]
+    args: ['@']
+    returns: {"one": 1, "two": 2}
+  from_items_duplicate_entry:
+    context: [["one", 1], ["two", 2], ["one", 3]]
+    args: ['@']
+    returns: {"one": 3, "two": 2}

functions/items.yml

@@ -0,0 +1,25 @@
+name: items
+topic: misc
+args:
+  required:
+  - name: obj
+    type: [object]
+    desc: ''
+  optional: []
+returns:
+  type: ['array[any]']
+  desc: ''
+desc: |2
+  Returns an array of key-value pairs for the provided input object.
+  Each pair is a 2-item array with the first item being the key and
+  the second item being the value.
+  This function is the inversed of the `from_items()` function.
+
+  Note that because JSON hashes are inheritently unordered,
+  the key value pairs of the provided object $obj are inheritently unordered.
+  Implementations are not required to return values in any specific order.
+examples:
+  basic:
+    context: {"a": "first", "b": "second"}
+    args: ['@']
+    returns: [["a", "first"], ["b", "second"]]

functions/zip.yml

@@ -0,0 +1,32 @@
+name: zip
+topic: misc
+args:
+  required:
+  - name: arg
+    type: ['array[any]']
+    desc: ''
+  variadic:
+    type: ['array[any]']
+    desc: ''
+  optional: []
+returns:
+  type: ['array[array[any]]']
+  desc: ''
+desc: |2
+  Accepts one or more arrays as arguments and returns an array of arrays
+  in which the _i-th_ array contains the _i-th_ element from each of the
+  argument arrays.
+  The returned array is truncated to the length of the shortest argument array.
+examples:
+  zip:
+    context:
+    args:
+      - ["a", "b"]
+      - [1, 2]
+    returns: [["a", 1], ["b", 2]]
+  zip_sparse:
+    context:
+    args:
+      - ["a", "b", "c"]
+      - [1, 2]
+    returns: [["a", 1], ["b", 2]]

jep-013-object-manipulation-functions.md

@@ -0,0 +1,85 @@
+# Object Manipulation Functions
+
+|||
+|---|---
+| **JEP**    |  13
+| **Author** | Jonathan Stewmon
+| **Created**| 21-March-2016
+| **SemVer** | MINOR
+| **Status**| Draft
+
+## Abstract
+
+As a JSON querying language, JMESPath has long needed some functions to manipulate JSON objects.
+
+This JEP introduces built-in functions to extract a list of key/value pairs from a JSON object and conversely converting an array of key/value pairs to a JSON object.
+
+## Specification
+
+### items
+
+```
+array[array[any]] items(object $obj)
+```
+
+Returns a an array of key value pairs for the provided object `$obj`. Each pair is a 2-item array with the first item being the key and the second item being the value. This function is the inverse of the `from_items()` function.
+
+Note that because JSON hashes are inheritently unordered, the key value pairs of the provided object `$obj` are inheritently unordered.  Implementations are not required to return values in any specific order. 
+
+For example, given the input:
+
+```json
+{"a": "first", "b": "second", "c": "third"}
+```
+
+The expression ``items(@)`` could have any of these return values:
+
+- ``[["a", "first"], ["b", "second"], ["c", "third"]]``
+- ``[["a", "first"], ["c", "third"], ["b", "second"]]``
+- ``[["b", "second"], ["a", "first"], ["c", "third"]]``
+- ``[["b", "second"], ["c", "third"], ["a", "first"]]``
+- ``[["c", "third"], ["a", "first"], ["b", "second"]]``
+- ``[["c", "third"], ["b", "second"], ["a", "first"]]``
+
+If you would like a specific order, consider using the ``sort_by`` function.
+
+### Examples
+
+|Given|Expression|Result
+|---|---|---
+|``{"a": "first", "b": "second"}``|``items(@)``|``[["b", "second"], ["a", "first"]]``
+|``{"z": "last", "b": "second"}``|``sort_by(items(@), &[0])``|``[["b", "second"], ["z", "last"]]``
+|``{"z": "last", "b": "second"}``|``sort_by(items(@), &[1])``|``[["z", "last"], ["b", "second"]]``
+
+### from_items
+
+```
+object from_items(array[array[any]] $arg)
+```
+Returns an object from the provided array of key value pairs. This function is the inverse of the `items()`.
+
+### Examples
+
+|Given|Expression|Result
+|---|---|---
+|``[["one", 1], ["two", 2]]``|``from_items(@)``|``{"one": 1, "two": 2}``
+|``[["one", 1], ["two", 2], ["one", 3]]``|``from_items(@)``|``{"one": 3, "two": 2}``
+
+### zip
+
+```
+array[array[any]] zip([array[any] $arg, [, array[any] $...]])
+```
+
+Accepts one or more arrays as arguments and returns an array of arrays in which the *i-th* array contains the *i-th* element from each of the argument arrays. The returned array is truncated to the length of the shortest argument array.
+
+### Examples
+
+|Expression|Result
+|---|---
+|``zip(`["a", "b"]`, `[1, 2]`)``|``[["a", 1], ["b", 2]]``
+|``zip(`["a", "b", "c"]`, `[1, 2]`)``|``[["a", 1], ["b", 2]]``
+
+## Compliance tests
+
+A new `objects.json` file will be added to the compliance test suite.