String type
Ensure the field's value is a valid string
. Empty strings are allowed, and you must handle them using the convertEmptyStringsToNull
configuration option.
import vine from '@vinejs/vine'
const schema = vine.object({
username: vine.string()
})
Using the following modifiers, you may mark the field as optional
or nullable
.
See also: Working with undefined
and null
values
{
username: vine.string().nullable()
}
{
username: vine.string().optional()
}
Defining error messages
You may define custom error messages for the following string-based rules.
const messages = {
string: 'The {{ field }} field must be a string',
email: 'The {{ field }} field must be a valid email address',
regex: 'The {{ field }} field format is invalid',
url: 'The {{ field }} field must be a valid URL',
activeUrl: 'The {{ field }} field must be a valid URL',
alpha: 'The {{ field }} field must contain only letters',
alphaNumeric: 'The {{ field }} field must contain only letters and numbers',
minLength: 'The {{ field }} field must have at least {{ min }} characters',
maxLength: 'The {{ field }} field must not be greater than {{ max }} characters',
fixedLength: 'The {{ field }} field must be {{ size }} characters long',
confirmed: 'The {{ field }} field and {{ otherField }} field must be the same',
endsWith: 'The {{ field }} field must end with {{ substring }}',
startsWith: 'The {{ field }} field must start with {{ substring }}',
sameAs: 'The {{ field }} field and {{ otherField }} field must be the same',
notSameAs: 'The {{ field }} field and {{ otherField }} field must be different',
in: 'The selected {{ field }} is invalid',
notIn: 'The selected {{ field }} is invalid',
ipAddress: 'The {{ field }} field must be a valid IP address',
uuid: 'The {{ field }} field must be a valid UUID',
ulid: 'The {{ field }} field must be a valid ULID',
ascii: 'The {{ field }} field must only contain ASCII characters',
creditCard: 'The {{ field }} field must be a valid {{ providersList }} card number',
hexCode: 'The {{ field }} field must be a valid hex color code',
iban: 'The {{ field }} field must be a valid IBAN number',
jwt: 'The {{ field }} field must be a valid JWT token',
coordinates: 'The {{ field }} field must contain latitude and longitude coordinates',
mobile: 'The {{ field }} field must be a valid mobile phone number',
passport: 'The {{ field }} field must be a valid passport number',
postalCode: 'The {{ field }} field must be a valid postal code',
}
vine.messagesProvider = new SimpleMessagesProvider(messages)
Validations
Following is the list of validation rules you can apply on a string.
Validate the field's value to be a valid email address. The validation is performed using the validator.js library, and you may pass all the options accepted by the validator.isEmail method.
See also: normalizeEmail
vine.object({
email: vine
.string()
.email(optionsGoesHere)
})
regex
Validate the field's value against a pre-defined regular expression.
vine.object({
username: vine
.string()
.regex(/^[a-zA-Z0-9]+$/)
})
vine.object({
username: vine
.string()
.regex(new RegExp('^[a-zA-Z0-9]+$'))
})
url
Validate the field's value to be a valid URL. The validation is performed using the validator.js library, and you may pass all the options accepted by the validator.isURL method.
vine.object({
health_checks_url: vine
.string()
.url({
require_protocol: true,
protocols: ['http','https','ftp']
})
})
activeUrl
Ensure the URL value of a field has valid A
or AAAA
DNS records. The DNS lookup is performed using the dnsPromises.resolve method.
vine.object({
health_checks_url: vine
.string()
.activeUrl()
})
alpha
Validate the field's value only to contain letters, i.e.: [a-z]
and [A-Z]
. Optionally allow spaces, underscore, and dashes as well.
vine.object({
username: vine
.string()
.alpha({
allowSpaces: false,
allowUnderscores: true,
allowDashes: true,
})
})
alphaNumeric
Validate the field's value only to contain letters and numbers, i.e.: [a-z]
, [A-Z]
, and [0-9]
. Optionally allow spaces, underscore, and dashes as well.
vine.object({
username: vine
.string()
.alphaNumeric({
allowSpaces: false,
allowUnderscores: true,
allowDashes: true,
})
})
minLength
Enforce the string to have the minimum pre-defined length.
vine.object({
password: vine
.string()
.minLength(8)
})
maxLength
Enforce the string to have the maximum pre-defined length.
vine.object({
password: vine
.string()
.maxLength(32)
})
fixedLength
Enforce the string to have a fixed length.
vine.object({
pan_number: vine
.string()
.fixedLength(10)
})
confirmed
Ensure the field under validation is confirmed by having another field with the same name and _confirmation
suffix.
For example, You may use this rule to ensure the user confirms their password by typing it twice. If the field name is password
, the confirmation field name must be password_confirmation
.
const schema = vine.object({
password: vine
.string()
.confirmed()
})
const data = {
password: 'secret',
password_confirmation: 'secret'
}
const validator = vine.compile(schema)
await validator.validate(data)
You may modify the confirmation field name as follows.
const schema = vine.object({
password: vine
.string()
.confirmed({
confirmationField: 'passwordConfirmation'
})
})
endsWith
Ensure the field's value ends with the pre-defined substring.
vine.object({
email: vine
.string()
.endsWith('client_app.com')
})
startsWith
Ensure the field's value starts with the pre-defined substring.
vine.object({
email: vine
.string()
.startsWith('+91')
})
sameAs
Ensure the field's value under validation is the same as the other field's value.
vine.object({
password: vine.string(),
password_confirmation: vine
.string()
.sameAs('password'),
})
notSameAs
Ensure the field's value under validation is different from another field's value.
vine.object({
old_email: vine.string().email(),
email: vine
.string()
.email()
.notSameAs('old_email')
})
in
Ensure the field's value under validation is a subset of the pre-defined list.
See also: Enum data type for better type inference
vine.object({
role: vine
.string()
.in(['admin', 'moderator', 'writer'])
})
You may defer computing the list values by registering a callback. The callback must return an array of values.
vine.object({
state: vine.string().in(statesList()),
city: vine
.string()
.in((field) => {
return citiesList(field.parent.state)
})
})
notIn
Ensure the field's value under validation is not inside the pre-defined list.
vine.object({
username: vine
.string()
.notIn(['admin', 'root', 'superuser'])
})
Like the in
validation, you may defer computing the list values by registering a callback.
vine.object({
username: vine
.string()
.notIn(() => {
return ['admin', 'root', 'superuser']
})
})
ipAddress
Validate the field's value to be a valid IP Address. Optionally, you may enforce the IP version as 4
or 6
. Both ipv4
and ipv6
values are allowed by default.
vine.object({
ip: vine
.string()
.ipAddress({ version: 4 })
})
uuid
Ensure the field's value to be a valid uuid
. You may optionally enforce a specific uuid version (version 1, 2, 3, 4 or 5).
vine.object({
id: vine
.string()
.uuid({ version: [4] })
})
// Enforce multiple version.
vine.object({
id: vine
.string()
.uuid({ version: [2, 4, 5] })
})
ulid
Ensure the field's value to be a valid ulid
according to the canonical specs.
vine.object({
id: vine
.string()
.ulid()
})
ascii
Ensure the value contains ASCII characters only.
vine.object({
greeting: vine
.string()
.ascii()
})
creditCard
Ensure the field's value is a valid credit card number. Optionally, you can define an array of providers from the following list.
- amex
- dinersclub
- discover
- jcb
- mastercard
- unionpay
- visa
vine.object({
credit_card: vine
.string()
.creditCard()
})
// Only allow mastercard credit cards
vine.object({
credit_card: vine
.string()
.creditCard({ provider: ['mastercard'] })
})
You may define a callback function to compute the credit card options at runtime.
vine.object({
credit_card: vine
.string()
.creditCard((field) => {
return {
provider: ['mastercard', 'amex', 'visa']
}
})
})
hexCode
Ensure the value is a valid hex code for a color.
vine.object({
primary_color: vine.string().hexCode()
})
iban
Ensure the value is a valid IBAN (International Bank Account Number).
vine.object({
iban: vine.string().iban()
})
jwt
Ensure the value is formatted as a valid JWT (JSON Web Token).
vine.object({
authorization: vine.string().jwt()
})
coordinates
Ensure the value is a string with latitude and longitude coordinates.
vine.object({
delivery_location: vine
.string()
.coordinates()
})
mobile
Ensure the field's value is a valid mobile number. The validation is performed using the validator.js library, and you may pass all the options accepted by the validator.isMobilePhone method.
vine.object({
contact_number: vine
.string()
.mobile()
})
You may define a callback function to compute the options at runtime.
vine.object({
contact_number: vine
.string()
.mobile((field) => {
return {
locale: ['en-IN'],
strictMode: true,
}
})
})
passport
Ensure the field's value is formatted as a valid passport number for a given or multiple country codes.
vine.object({
passport: vine
.string()
.passport({
countryCode: ['IN', 'US', 'GB']
})
})
You may define a callback function to compute the options at runtime.
vine.object({
passport: vine
.string()
.passport((field) => {
return {
countryCode: [field.parent.country_code]
}
})
})
postalCode
Ensure the field's value is formatted as a valid postal code. Optionally, you can define an array of country codes as well.
vine.object({
postal_code: vine
.string()
.postalCode({ countryCode: ['IN'] })
})
You may define a callback function to compute the options at runtime.
vine.object({
postal_code: vine
.string()
.postalCode((field) => {
return {
countryCode: [field.parent.country_code]
}
})
})
Mutations
Following is the list of mutations you can apply to a string value. As the name suggests, mutations normalize or change the input value and do not perform any validations.
trim
Trim whitespaces from the value.
vine.object({
email: vine.string().trim().email()
})
normalizeEmail
The normalizeEmail
method normalizes the email address. The normalization is performed using the validator.js library, and you may pass all the options accepted by the validator.normalizeEmail method.
vine.object({
email: vine
.string()
.normalizeEmail({
all_lowercase: true,
gmail_remove_dots: true,
})
})
normalizeUrl
The normalizeUrl
method normalizes a URL value. The normalization is performed using the normalize-url package, and you may pass all the options accepted by the package.
vine.object({
health_checks_url: vine
.string()
.normalizeUrl({
normalizeProtocol: true,
forceHttps: true,
stripHash: true,
})
})
escape
The escape
method escapes HTML entities inside the string value.
vine.object({
about: vine.string().escape()
})
toUpperCase
Convert the field value to all uppercase.
vine.object({
role: vine
.string()
.toUpperCase()
})
toCamelCase
Convert the field value to camel case.
vine.object({
role: vine
.string()
.toCamelCase()
})
toLowerCase
Convert the field value to lowercase.
vine.object({
username: vine
.string()
.toLowerCase()
})