Skip to main content

Vault naming rules

This page describes the rules for valid names for:

  • Entities
  • Transformation bindings
  • Resources

Entities​

An entity is a:

  • Bundle
  • DataType
  • Collection
  • Property
  • Policy
  • Role
  • User
  • Action

The name of an entity can be any combination of alphanumeric ASCII characters (a-z, A-Z, 0-9) and underscore ('_'), except the first character cannot be an underscore or a digit. For example, em_Ploy33s_1 is a valid entity name. However, these are invalid entity names:

  • 1employees
  • _employees
  • -employees
  • employees
  • e mployees
  • employés

Names can be up to 450 characters long, except for the names of collections or properties, which are limited to 40 characters. In addition, the sum of the lengths of the name of a collection and any property in the collection cannot be more than 41 characters.

Entity names are case-sensitive. However, Vault does not allow two resource names to differ in case only.

For example, if a caller creates a collection by providing this body to the REST API add collection operation:

customers PERSONS (
    first_NAME STRING NOT NULL COMMENT "First Name",
);

The operation sets the property name to first_NAME.

Then, the value of an object's first_NAME property can be retrieved only by calling the REST API list objects method specifying props=first_NAME as a query parameter.

However, it is not possible to specify a collection like this:

customers PERSONS (
    first_NAME STRING NOT NULL COMMENT "First Name",
    first_name STRING NOT NULL COMMENT "First Name",
);

This is because 'first_NAME' and 'first_name' differ only in case.

Transformation bindings​

A transformation binding represents the application of a transformation to a property value or data type. The binding name consists of a property or data type name followed by a transformation name separated by a dot.

If the first element in the pair is a property name, the transformation binding is called a property transformation binding. If the first element in the pair is a data type, the transformation binding is called a type transformation binding.

For example:

  • this is a property transformation binding: personal_email.mask where personal_email is the name of a property and mask is the name of a transformation.
  • this is a type transformation binding: email.mask where email is a data type and mask is the name of a transformation.

Resource​

A resource specifies a set of data items referred to by a policy. A resource may be the string * or a string in the format: [collection_name]/[resource_type]/[resource_name]. In the formatted string:

  • collection_name is an entity name that may include one or zero * characters. It is used as a glob to match one or more collection names.
  • resource_type is one of the strings: tokens, types, properties, archived/properties, or archived/tokens.
  • resource_name is an entity name or a transformation binding that can include one or zero * characters.

These rules also apply to the resource_name:

  • If resource_type is tokens or archived/tokens, resource_name is ignored.
  • If resource_type is properties or archived/properties, resource_name is used as a glob to match one or more property names or property transformation binding.
  • If resource_type is types, resource_name is used as a glob to match one or more type names or type transformation bindings.

On this page