Skip to content

validation.md

Latest commit

 

History

History
525 lines (416 loc) · 5.39 KB

validation.md

File metadata and controls

525 lines (416 loc) · 5.39 KB
layout default
title Validation
parent Features
nav_order 4

Validation

YAML Schema provides various validation constraints that can be applied to types. This page covers enums, constants, and other validation features.

Enums

The enum keyword restricts values to a specific set of allowed values.

Basic Enum

# Schema
enum:
  - red
  - amber
  - green

Valid examples:

red
green

Invalid examples:

blue

Enum with Mixed Types

Enums can contain values of different types:

# Schema
enum:
  - red
  - amber
  - green
  - null
  - 42

Valid examples:

red
null
42

Invalid examples:

0

Enum with Type Constraint

You can combine enum with a type constraint:

# Schema
type: object
properties:
  version:
    type: integer
    enum: [1]

Valid examples:

version: 1

Invalid examples:

version: 2

Enum in Arrays

# Schema
type: array
prefixItems:
  - type: number
  - type: string
  - enum:
    - Street
    - Avenue
    - Boulevard
  - enum:
    - NW
    - NE
    - SW
    - SE

Valid examples:

- 1600
- Pennsylvania
- Avenue
- NW

Invalid examples:

- 24
- Sussex
- Drive

Enum with Numbers

# Schema
type: integer
enum: [1, 10, 100]

Valid examples:

1
10
100

Invalid examples:

101
# Schema
type: number
enum: [-1.0, 0.0, 1.0]

Valid examples:

-1.0
0.0
1.0

Invalid examples:

3.14

Constants

The const keyword requires the value to be exactly equal to a specific constant value.

Basic Const

# Schema
type: object
properties:
  country:
    const: United States of America

Valid examples:

country: United States of America

Invalid examples:

country: Canada

Const in Composition

Constants are often used with composition operators like oneOf:

# Schema
oneOf:
  - type: object
    properties:
      type:
        const: "integer"
      minimum:
        type: integer
      maximum:
        type: integer
    required:
      - type
  - type: object
    properties:
      type:
        const: "string"
    required:
      - type

Valid examples:

type: integer
type: integer
minimum: 1
maximum: 10
type: string

Invalid examples:

type: boolean

String Validation

Length Constraints

# Schema
type: string
minLength: 2
maxLength: 3

Valid examples:

"AB"
"ABC"

Invalid examples:

"A"
"ABCD"

Pattern Matching

# Schema
type: string
pattern: "^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$"

Valid examples:

"555-1212"
"(888)555-1212"

Invalid examples:

"(888)555-1212 ext. 532"
"(800)FLOWERS"

Number Validation

Multiples

# Schema
type: number
multipleOf: 10

Valid examples:

0
10
20

Invalid examples:

23

Range Constraints

# Schema
type: number
minimum: 0
exclusiveMaximum: 100

Valid examples:

0
10
99

Invalid examples:

-1
100
101

Available range keywords:

  • minimum - Inclusive minimum value
  • maximum - Inclusive maximum value
  • exclusiveMinimum - Exclusive minimum value
  • exclusiveMaximum - Exclusive maximum value

Array Validation

Contains

The contains keyword requires that at least one item in the array matches the schema:

# Schema
type: array
contains:
  type: number

Valid examples:

- life
- universe
- everything
- 42
- 1
- 2
- 3
- 4
- 5

Invalid examples:

- life
- universe
- everything
- forty-two

See Types for minItems, maxItems, uniqueItems, and minContains / maxContains with contains.

Object Validation

Required Properties

# Schema
type: object
properties:
  name:
    type: string
  email:
    type: string
required:
  - name
  - email

Valid examples:

name: William Shakespeare
email: bill@stratford-upon-avon.co.uk

Invalid examples:

name: William Shakespeare
address: Henley Street, Stratford-upon-Avon, Warwickshire, England
name: William Shakespeare
email: null

Note: A property with a null value is considered not being present.

Property Size

# Schema
type: object
minProperties: 2
maxProperties: 3

Valid examples:

a: 0
b: 1
a: 0
b: 1
c: 2

Invalid examples:

{}
a: 0
a: 0
b: 1
c: 2
d: 3

Property Names

# Schema
type: object
propertyNames:
  pattern: "^[A-Za-z_][A-Za-z0-9_]*$"

Valid examples:

_a_proper_token_001: "value"

Invalid examples:

-001 invalid: "value"

Descriptions

You can add descriptions to schemas for documentation purposes. Descriptions don't affect validation:

# Schema
type: string
description: "First name"
# Schema
description: A string or a number
anyOf:
  - type: string
  - type: number
# Schema
type: number
description: The description