Adding Custom Rules

Keywords

In fluffy rules, .self, .schema and .data are reserved keywords that refer to the fluffy object the rule is being applied to and the schema/data being validated, respectively.

.self is the fluffy object the rule is being applied to, so for schema validation it is the Schema object and for data transformation/validation it is the Validator object. This allows the rule functions to access properties of the relevant fluffy object, such as the Registry of rules.

.schema is used in the schema validation function to refer to the full schema being validated, and .data is used in the data transformation/validation function to refer to the full data being validated. This allows the rule functions to access other fields in the schema/data when operating on a particular field.

Rule function arguments

Schema validation functions are passed the schema field as a positional argument, and then .schema and .self as named arguments. Therefore, schema validation functions can be defined in these ways:

Data transformation/validation functions are passed the data field and the schema field as positional arguments, respectively, and then .data and .self as named arguments. Therefore, data transformation/validation functions can be defined in these ways:

Schema validation function

The schema validation function checks the validity of the schema field for the rule. It should return NULL if the schema field is valid, and a character string (to be used as an error message) if it is invalid.

The following would be an example of a schema validation function that checks that the schema field is a length 1 character:

schema_validation_fn <- function(field, ...) {
  if (!is.character(field) || length(field) != 1L) {
    "Must be a length 1 character."
  }
}

Schema validation is optional. If a function is not provided, the rule will be added without any schema validation, and any schema value will be accepted for the rule. In this case, the schema validation function would simply be an empty function (this is the same as the implementation of the builtin default rule):

allow_any_schema_fn <- function(field, ...) {}

Data transformation/validation function

The data transformation/validation function applies the rule to the data. Unlike the schema validation function, a named list must be returned, with the following named element(s) determining the behaviour:

return(list(error = ..., data = ..., continue = ...))

• error: character string of the error message and if returned, signals that the data is invalid. If not returned or NULL, the data is considered valid for that rule.
• data: the transformed data for the field. If not returned or NULL, the original data remains. If both error and data are returned, the data will be transformed but still be considered invalid.
• continue: a boolean to indicate whether to continue validating the rest of the schema rules in the node. This is used in the builtin in control rules that determine whether validation should proceed or not, but can be used in any rule. If not returned or NULL, it defaults to TRUE.

The following would be an example of a data transformation/validation function that checks that the data field is a length 1 character, pasting the schema field onto it if so, and erroring if not:

data_validation_fn <- function(data_field, schema_field, ...) {
  if (!is.character(data_field) || length(data_field) != 1L) {
    list(error = "Data must be a length 1 character.")
  } else {
    list(data = paste0(data_field, schema_field))
  }
}

An example of a builtin rule that alters control flow with continue is the required rule. See the following example where the other rules in the schema node do not error despite there being no data for the node, as required returns continue = FALSE and thus stops validation of the rest of the schema rules for that node:

Validator(
  data = list(a = 1),
  schema = list(
    b = list(
      required = FALSE,
      type = "character",
      min_length = 5L
    )
  )
)@valid
#> [1] TRUE

Rule type

The rule type determines when the rule is applied when the Validator is run. Four separate passes are undertaken during data validation, with rules being applied depending on their specified type in the associated Registry:

r <- Registry()
r@control_rules # first pass
#> [1] "required" "default"
r@transform_rules # second pass
#> [1] "coerce" "apply"
r@validate_rules # third pass
#>  [1] "type"           "inherits"       "allowed"        "forbidden"     
#>  [5] "unique"         "positive"       "negative"       "finite"        
#>  [9] "allow_na"       "sorted"         "min_val"        "max_val"       
#> [13] "min_length"     "max_length"     "min_nrow"       "max_nrow"      
#> [17] "min_nchar"      "max_nchar"      "nzchar"         "regex"         
#> [21] "levels"         "ordered_levels" "dependency"     "dependencies"  
#> [25] "predicate"
r@finalize_rules # fourth pass
#> [1] "coerce_last" "apply_last"

The rule_type given must match one of these categories, and determines if the custom rule is applied in the first, second, third, or fourth pass. Custom rules do not need to strictly follow these category definitions, but it is recommended.

The order in which rules within categories are run is determined by the individual order of the associated Registry property, which can be edited.

The ‘finalize’ pass behaves slightly differently to the others, in that rules in this group are only applied if there are no errors from the previous passes in that schema node.