Custom data types
Discover how to add custom data types to Vault and how they work with policies
Vault includes a set of built-in data types. Vault also enables you to define custom data types. These custom data types can be assigned to properties and used just like the built-in types.
You can not base a custom type on another custom type (only on the built-in types).
This page describes how to define custom data types dynamically or using a configuration file, and how policies control access to custom data types.
Define custom data types dynamically
Data types configuration file
Specifying bundles and data types with the API or CLI means you need to run code to insert custom data types after Vault loads. However, you can load custom data types and their associated bundles when you start Vault. The file is loaded the first time Vault start and reloaded on subsequent starts if the
PVAULT_SERVICE_UPDATE_SCHEMA_ON_START service and features environment variable is
If you're using the hosted version of Vault, contact us if you wish set Vault to load the configuration file on each start.
The data types configuration file is called
pvault.types.toml and stored in the directory
/etc/pvault/conf.d. If the file is missing, Vault skips the data type loading process.
The types configuration file contains custom data type definitions and bundle declarations. Each bundle declaration includes the name of the file that contains the bundle content. These files are loaded from
If the format of the types configuration file is invalid, any bundle files are missing, or the addition of the bundles or data types fails, Vault does not load.
Types configuration file format
The types configuration file is a TOML file with two sections.
[types] contains the definitions of the custom data types.
[bundles] contains the list of bundles.
This is an example of a valid
description = "Age in years"
based_on = "INTEGER"
validator = "sample.between_0_120"
normalizer = "sample.identity"
transformers = ["sample.modulo_10"]
description = "Case insensitive name"
based_on = "NAME"
normalizer = "sample.lower_case"
description = "Interval"
based_on = "STRING"
validator = "sample.interval_HH_MM_SS"
transformers = ["sample.mask_last_4", "sample.truncate_last_4"]
description = "HTTPS URL"
based_on = "URL"
validator = "sample.is_https"
description = "Date of birth with age"
based_on = "DATE_OF_BIRTH"
transformers = ["sample.age"]
description = "Protected email"
based_on = "EMAIL"
transformers = [
description = "This bundle contains some sample transformers, normalizers and validators"
file_name = "sample.js"
description = "This bundle contains the IDOR transformer and all its dependencies"
file_name = "idor.js"
This example file:
- Defines the custom data types
- Declares the bundles
Type functions, if specified in the definition of a data type, use the qualified name format
<bundle-name>is the name of the bundle where the type function is defined and exported.
<function-name>is the exported name of the function.
See (Exporting a type function)[/guides/reference/bundles#export-type-functions] for more information.
All the bundles referenced by data types in the
[types] section must be declared in the
The declaration of each bundle specifies a file name for the bundle. A file with this name must be in the
Types configuration file validation
Vault does not start if:
- The file does not comply with the TOML format.
- A type refers to one or more validators, normalizers, or transformers that are not defined.
- A type has the same name as a built-in type.
- A custom type is used in a property of a collection but is not defined.
Custom data types and policies
Although custom data types are based on other data types, policies consider custom data types to be distinct. Take the case of a custom data type called GMAIL based on the built-in type EMAIL. A policy that enables access to all properties based on EMAIL data type (with a 'resource' of
*/types/email) does not provide access to properties based on the GMAIL data type.
Using an appropriate naming scheme, you can provide hierarchical access to properties in policies based on data types using wildcard matching. For example, in the case of a GMAIL data type based on an EMAIL data type, a 'resource' of
*/types/*mail matches property based on both the GMAIL and EMAIL data type.