Skip to content

Built in rules

Jump to bottom
Esta Nagy edited this page Jul 24, 2020 · 8 revisions

This page lists all the existing rule implementations we have to offer.

How to use this document...

Each rule has two mandatory parameters and can have additional parameters on top of those at the discretion of the implementation. We will detail only the additional parameters at the specific rules to avoid copy-pasting the basics.

The mandatory configuration parameters are:

Parameter Example Description
name rule-name The name used when the rule is registered.
path $.json.path The path used to find out which parts of the JSON are in scope for the rule.

The optional parameters are defined under the param object.

Each rule has a version when it was added to the app, a class implementing them, a name they are registered with, a parameter list defining how they can be configured, a description stating what they are supposed to do, and we will show an example configuration as well.

Rule implementations

Add

Name: add

Class: JsonAddRule

Since version: 1.0.0

Parameters

Name Type Description
key Supplier < String > The supplier that will define the key of the new node.
value Supplier < Object > The supplier that will define the value assigned to the new node identified by the key.

Description

This rule adds a new key under the JSON Node matching the JSON Path of the rule. Therefore, it is necessary to define the JSON Path in a way that is locating an object typed node. The key of the new child is provided by the key Supplier, the value assigned to it is supplied by the value Supplier.

Example configuration

Applying this configuration

actions:
  - name: "demo"
    rules:
      - name: "add"
        path: "$.accounts[*]"
        params:
          key: # this is the node defining the first supplier
            name: "staticString"
            value: "address"
          value: # this is the node defining the second supplier
            name: "staticJson"
            value: '{"home":"123 Main street, SomeCity"}'

On this input

{
  "accounts": [
    {
      "id": 1,
      "name": "John Doe"
    },
    {
      "id": 2,
      "name": "Jane Doe"
    }
  ]
}

Produces this output

{
  "accounts": [
    {
      "id": 1,
      "name": "John Doe",
      "address": {
        "home": "123 Main street, SomeCity"
      }
    },
    {
      "id": 2,
      "name": "Jane Doe",
      "address": {
        "home": "123 Main street, SomeCity"
      }
    }
  ]
}

Calculate

Name: calculate

Class: JsonCalculateRule

Since version: 1.1.0

Parameters

Name Type Description
predicate Predicate < BigDecimal > optoinal The predicate that will determine whether we should apply the function.
numberFunction Function < BigDecimal , BigDecimal > The function that will tell the rule what kind of calculation needs to be done.

Description

This rule performs some kind of calculation on the JSON Node value matching the JSON Path of the rule. The optional Predicate we can define allows conditional calculation while the Function that does the transformation defines what we will do.

Example configuration

Applying this configuration

actions:
  - name: "demo"
    rules:
      - name: "calculate"
        path: "$.posts[*].views"
        params:
          predicate: # this is the node defining the predicate
            name: "notNull"
          numberFunction: # this is the node defining the numerical calculation
            name: "add"
            operand: 1
            scale: 0

On this input

{
  "posts": [
    {
      "id": 1,
      "title": "Post title 1",
      "likes": 30,
      "views": 20
    },
    {
      "id": 2,
      "title": "Post title 2",
      "likes": 0,
      "views": 5
    }
  ]
}

Produces this output

{
  "posts": [
    {
      "id": 1,
      "title": "Post title 1",
      "likes": 30,
      "views": 21
    },
    {
      "id": 2,
      "title": "Post title 2",
      "likes": 0,
      "views": 6
    }
  ]
}

The example shows that the number of views were increased by 1 in both cases when we applied the rule.

Copy

Name: copy

Class: JsonCopyRule

Since version: 1.0.0

Parameters

Name Type Description
key Supplier < String > The supplier that will define the key we want to copy.
to.value JsonPath The destination path where this rule will attempt to create the copied node.

Description

This rule identifies a single object using the JSON Path we provide in the "path" parameter and copies it as a child under all of the nodes matching the "to" JSON Path parameter with the new key named as the "key" Supplier defines.

Example configuration

Applying this configuration

actions:
  - name: "demo"
    rules:
      - name: "copy"
        path: "$.accounts[0].name"
        params:
          key: # this is the node defining the key supplier
            name: "staticString"
            value: "birthName"
          to: # this is the node for our destination JSON Path
            value: "$.accounts[0]"

On this input

{
  "accounts": [
    {
      "id": 1,
      "name": "John Doe"
    },
    {
      "id": 2,
      "name": "Jane Doe"
    }
  ]
}

Produces this output

{
  "accounts": [
    {
      "id": 1,
      "name": "John Doe",
      "birthName": "John Doe"
    },
    {
      "id": 2,
      "name": "Jane Doe"
    }
  ]
}

Delete from

Name: deleteFrom

Class: JsonDeleteFromMapRule

Since version: 1.1.0

Parameters

Name Type Description
predicate Predicate < Map < String , Object > > optoinal Determines whether any deletion should be performed for the matching node
keepKey Predicate < String > optoinal The predicate that will be used to test whether a key should be kept, keeping only the matching keys.
deleteKey Predicate < String > optoinal The predicate that will be used to test whether a key should be deleted, deleting all the matching keys.
keepValue Predicate < Object > optoinal The predicate that will be used to test whether a key should be kept, keeping only the matching keys.
deleteValue Predicate < Object > optoinal The predicate that will be used to test whether an entry should be deleted, deleting all of them with matching values.

Description

This rule performs a Map operation on the JSON Node matching the JSON Path of the rule, therefore the path must match Objects/Maps to make it work. All parameters are optional, but it is required to fill at least one of them in order to have meaningful rule configuration.

Example configuration

Applying this configuration

actions:
  - name: "demo"
    rules:
      - name: "deleteFrom"
        path: "$.accounts[*]"
        params:
          predicate:
            name: "containsKey"
            key: "address"
          keepKey:
            name: "regex"
            pattern: ^[a-z]+$
          deleteKey:
            name: "regex"
            pattern: ^password$

On this input

{
  "accounts": [
    {
      "address": {
        "home": "123 Main street, SomeCity"
      },
      "id": 1,
      "name": "John Doe",
      "password": "21fe12e12ef7f8a123db123",
      "totalComments": 0
    },
    {
      "id": 2,
      "name": "Jane Doe",
      "totalComments": 10
    }
  ]
}

Produces this output

{
  "accounts": [
    {
      "address": {
        "home": "123 Main street, SomeCity"
      },
      "id": 1,
      "name": "John Doe"
    },
    {
      "id": 2,
      "name": "Jane Doe",
      "totalComments": 10
    }
  ]
}

Delete

Name: delete

Class: JsonDeleteRule

Since version: 1.0.0

Parameters: < NONE >

Description

This rule deletes all nodes from the document matching the path parameter.

Example configuration

Applying this configuration

actions:
  - name: "demo"
    rules:
      - name: "delete"
        path: "$.accounts[*].id"

On this input

{
  "accounts": [
    {
      "id": 1,
      "name": "John Doe"
    },
    {
      "id": 2,
      "name": "Jane Doe"
    }
  ]
}

Produces this output

{
  "accounts": [
    {
      "name": "John Doe"
    },
    {
      "name": "Jane Doe"
    }
  ]
}

Rename

Name: rename

Class: JsonRenameRule

Since version: 1.0.0

Parameters

Name Type Description
oldKey Supplier < String > Provides the name of the key we want to rename under the node matching the path parameter at the time of evaluation.
newKey Supplier < String > Provides the new name we want to use after the child node was renamed.

Description

This rule renames the key of a child node identified by the JSON Path we provide in the path parameter.

Example configuration

Applying this configuration

actions:
  - name: "demo"
    rules:
      - name: "rename"
        path: "$.accounts[*]"
        params:
          oldKey: # this is the node defining the first supplier
            name: "staticString"
            value: "name"
          newKey: # this is the node defining the second supplier
            name: "staticString"
            value: "fullName"

On this input

{
  "accounts": [
    {
      "id": 1,
      "name": "John Doe"
    },
    {
      "id": 2,
      "name": "Jane Doe"
    }
  ]
}

Produces this output

{
  "accounts": [
    {
      "id": 1,
      "fullName": "John Doe"
    },
    {
      "id": 2,
      "fullName": "Jane Doe"
    }
  ]
}

Replace map

Name: replaceMap

Class: JsonReplaceMapRule

Since version: 1.1.0

Parameters

Name Type Description
predicate Predicate < Map < String , Object > > optoinal The predicate that will determine whether we need to run the rule on the matching path.
mapFunction Function < Map < String , Object > , Map < String , Object > > The function that defines the transformation which needs to be done on the selected map/object.

Description

This rule performs a Map operation on the JSON Node matching the JSON Path of the rule, therefore the path must match Objects/Maps to make it work. The optional Predicate can be used to condition the transformation on a test, while the Function is responsible for the heavy-lifting by defining the transformation.

Example configuration

Applying this configuration

actions:
  - name: "demo"
    rules:
      - name: "replaceMap"
        path: "$.accounts[*]"
        params:
          predicate:
            name: "containsKey"
            key: "billingAddress"
          mapFunction:
            name: "cloneKey"
            from: "billingAddress"
            to: "shippingAddress"

On this input

{
  "accounts": [
    {
      "billingAddress": "123 Main street, SomeCity",
      "id": 1,
      "name": "John Doe"
    },
    {
      "id": 2,
      "name": "Jane Doe"
    }
  ]
}

Produces this output

{
  "accounts": [
    {
      "billingAddress": "123 Main street, SomeCity",
      "id": 1,
      "name": "John Doe",
      "shippingAddress": "123 Main street, SomeCity"
    },
    {
      "id": 2,
      "name": "Jane Doe"
    }
  ]
}

Replace

Name: replace

Class: JsonReplaceRule

Since version: 1.0.0

Parameters

Name Type Description
predicate Predicate < String > optoinal Adds an opportunity to filter by value before we apply the replace stringFunction.
stringFunction Function < String , String > Defines how the existing value needs to change during the operation.

Description

This rule is similar to the rename rule, but instead of changing the key of a node, it operates on the value of the String nodes matching the path parameter.

Example configuration

Applying this configuration

actions:
  - name: "demo"
    rules:
      - name: "replace"
        path: "$.accounts..lastName"
        params:
          stringFunction: # this is where we define our regex based replace
            name: "regex"
            pattern: (?<firstName>[A-Za-z\-]+) (?<lastName>[A-Za-z\-]+)
            replacement: "${lastName}"
          predicate: # doing it for all Strings
            name: "anyString"
      - name: "replace"
        path: "$.accounts..firstName"
        params:
          stringFunction: # this is where we define our literal based replace
            name: "replace"
            find: " Doe"
            replace: ""
          predicate: # we will do it only for non-null values
            name: "notNull"

On this input

{
  "accounts": [
    {
      "accountId": 1,
      "firstName": "John Doe",
      "lastName": "John Doe"
    },
    {
      "accountId": 2,
      "firstName": "Jane Doe",
      "lastName": "Jane Doe"
    }
  ]
}

Produces this output

{
  "accounts": [
    {
      "accountId": 1,
      "firstName": "John",
      "lastName": "Doe"
    },
    {
      "accountId": 2,
      "firstName": "Jane",
      "lastName": "Doe"
    }
  ]
}

JSON Schema validate

Name: validate

Class: JsonValidationRule

Since version: 1.2.0

Parameters

Name Type Description
schema Supplier < JsonSchema > The supplier providing the schema we will use for validation.
onFailure.transformation TransformationControlStrategy Defines how the transformation should handle a validation failure.
onFailure.violation ViolationStrategy Defines how the rule should document/report the violations.

Description

This rather complex rule validates the document processed by the rule against a schema that is supplied by the "schema" parameter. In case the validation passed, the rule is considered to be finished and nothing else happens. Otherwise the rule will use the defined strategies which are received as parameters to handle the failure as requested. The transformation strategy decides whether the transformation should be considered as aborted (no output provided), failed (partial results are kept allowing addition of extra validation specific information) or successful (basically ignoring the fact that the validation failed). The violation strategy defines whether we want to log the violations to the console, add violations and some reasoning into the JSON itself or just simply ignore the violations.

Example configuration

Applying this configuration

actions:
  - name: "demo"
    rules: # this is where our rule is defined
      - name: "validate"
        path: "$"
        params:
          schema: # this is where our schema validation node is
            name: "jsonSchema"
            source: # using the input JSON file as the schema to validate itself
              name: "file"
              path: "src/main/resources/examples/json/validation-input.json"
          onFailure:
            # we will stop the processing but save partial results
            transformation: "SKIP_REST"
            # add violation errors to the document itself
            violation: "COMMENT_JSON"

On this input

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "properties": {
    "$schema": {
      "type": "string",
      "const": "http://json-schema.org/draft-07/schema"
    },
    "properties": {
      "type": "object",
      "properties": {
        "$schema": {
          "type": "object"
        },
        "properties": {
          "type": "object"
        }
      },
      "required": [
        "$schema",
        "properties"
      ],
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

Produces this output

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "properties": {
    "$schema": {
      "type": "string",
      "const": "http://json-schema.org/draft-07/schema"
    },
    "properties": {
      "type": "object",
      "properties": {
        "$schema": {
          "type": "object"
        },
        "properties": {
          "type": "object"
        }
      },
      "required": [
        "$schema",
        "properties"
      ],
      "additionalProperties": false
    }
  },
  "additionalProperties": false,
  "$_yippee-schema-violation": [
    {
      "message": "$.additionalProperties: is not defined in the schema and the schema does not allow additional properties",
      "path": "$"
    }
  ]
}

The above example shows that the additionalProperties node caused itself to be invalid as it was not listed in the properties object as an allowed key.

GitHub issues by-label

GitHub open issues

GitHub license

Clone this wiki locally