Converters and Validators in navl Schemas

working on moving this document into validators.py and converters.py so that it's part of the official docs: https://github.com/ckan/ckan/pull/1841

Accepted Converter and Validator types

Converters and Validators are any of the following:

1. a formencode Validator class

   an instance will be created and .to_python(value, state=context) will be called on it. formencode.Invalid exceptions raised will add messages to errors for that field, and validation will continue.

   The value returned from a formencode validator is discarded, so these may only be used for validation and not for converting values.

2. a formencode Validator instance

   similar to above except this instance will be used.

3. a callable object converter(value)

   commonly used example: unicode to force the type of data to unicode for ascii (ONLY!) strings

   if a ckan.lib.navl.dictization_functions.Invalid exception is raised its .error message will be added to the errors for that field and validation will continue.

   The value returned from this callable will replace the value in converted_data

4. a callable object converter(key, converted_data, errors, context)

   commonly used example: ckan.lib.navl.validators.ignore_missing which stops further validation if the field data is missing.

   if a ckan.lib.navl.dictization_functions.Invalid exception is raised its .error message will be added to the errors for that field and validation will continue.

   The return value of this callable is ignored.

5. a callable object converter(value, context)

   commonly used example: ckan.lib.navl.validators.convert_int which converts value to an integer or raises an Invalid exception with a helpful error message.

   if a ckan.lib.navl.dictization_functions.Invalid exception is raised its .error message will be added to the errors for that field and validation will continue. The value returned from this callable will replace the value in converted_data

   The value returned from this callable will replace the value in converted_data

Special Exceptions

Any converter or validator may raise a ckan.lib.navl.dictization_functions.StopOnError to stop the processing of further converters and validators specified for the same field. This exception does not cause an error to be added to the errors.

Parameters Passed to Converters and Validators

Depending on the Converter or Validator type some of the following parameters will be passed:

value

same as converted_data[key]

key

a flattened name of the field being validated, e.g. ("notes",)

converted_data

a dict with flattened field names as the keys and the field data as values and the special value ckan.lib.navl.dictization_functions.missing used for fields not provided

validators/converters passed this dict MUST replace values in it themselves

errors

a dict with flattened field names as the keys and a list of error messages as the values, initialized to empty lists to start.

validators/converters passed this dict may insert values into it themselves or raise a ckan.lib.navl.dictization_functions.Invalid-derived exception with the error to be added

context

a dict containing items such as:

• 'package' - the dataset being edited
• 'pending': True or False ???
• 'message': '' ???
• 'save': True when saving a dataset, else False
• 'session': sqlalchemy session object,
• 'user': user name as a string, see also the Pylons c object and c.userobj.