Skip to content

types.md

Latest commit

 

History

History
812 lines (639 loc) · 9.08 KB

types.md

File metadata and controls

812 lines (639 loc) · 9.08 KB
layout default
title Types
parent Features
nav_order 2

Types

YAML Schema supports validation for all YAML data types. This page covers string, number, integer, boolean, null, array, and object types.

String Type

The string type validates text values.

Basic String Validation

# Schema
type: string

Valid examples:

"Déjà vu"
""
"42"

Invalid examples:

42
true

String Length Constraints

# Schema
type: string
minLength: 2
maxLength: 3

Valid examples:

"AB"
"ABC"

Invalid examples:

"A"
"ABCD"

minLength and maxLength count Unicode scalar values (code points), not UTF-8 bytes. For example, with maxLength: 2, "αβ" is valid and "αβγ" is too long.

For dates, emails, URIs, and other standard string shapes, see String formats.

String 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 Types

Number Type

The number type validates both integers and floating-point numbers.

# Schema
type: number

Valid examples:

42
3.14

Invalid examples:

"I'm a string"

Integer Type

The integer type validates whole numbers. Note that 1.0 is considered an integer.

# Schema
type: integer

Valid examples:

42
-1
1.0

Invalid examples:

3.1415926
"42"

Number Constraints

Multiples

# Schema
type: number
multipleOf: 10

Valid examples:

0
10
20

Invalid examples:

23

Range Validation

# Schema
type: number
minimum: 0
exclusiveMaximum: 100

Valid examples:

0
10
99

Invalid examples:

-1
100
101

Note: minimum is inclusive, while exclusiveMaximum is exclusive.

Boolean Type

The boolean type validates true/false values.

# Schema
type: boolean

Valid examples:

true
false

Invalid examples:

"true"

Null Type

The null type validates only null values.

# Schema
type: null

Valid examples:

null

Invalid examples:

false
0
""

Array Type

The array type validates ordered lists of values.

Basic Array Validation

# Schema
type: array

Valid examples:

- 1
- 2
- 3
- 4
- 5
- 3
- different
- types: "of values"

Invalid examples:

Not: "an array"

Array Items

# Schema
type: array
items:
  type: number

Valid examples:

- 1
- 2
- 3
- 4
- 5
[]

Invalid examples:

- 1
- 2
- "3"
- 4
- 5

Note: A single non-matching item causes the entire array to be invalid. Empty arrays are always valid.

Tuple Validation with prefixItems

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

Valid examples:

- 1600
- Pennsylvania
- Avenue
- NW
- 10
- Downing
- Street
- 1600
- Pennsylvania
- Avenue
- NW
- Washington

Invalid examples:

- 24
- Sussex
- Drive
- Palais de l'Élysée

Additional Items

By default, additional items beyond prefixItems are allowed. You can restrict this:

# Schema
type: array
prefixItems:
  - type: number
  - type: string
items: false

Valid examples:

- 1600
- Pennsylvania
- Avenue
- NW
- 1600
- Pennsylvania
- Avenue

Invalid examples:

- 1600
- Pennsylvania
- Avenue
- NW
- Washington

You can also specify a schema for additional items:

# Schema
type: array
prefixItems:
  - type: number
  - type: string
items:
  type: string

Valid examples:

- 1600
- Pennsylvania
- Avenue
- NW
- Washington

Invalid examples:

- 1600
- Pennsylvania
- Avenue
- NW
- 20500

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

minItems and maxItems

# Schema
type: array
minItems: 2

Too few elements (including []) fails validation. maxItems rejects arrays longer than the limit; an empty array is always allowed when minItems is not set.

Combined with items:

type: array
minItems: 2
maxItems: 4
items:
  type: number

uniqueItems

When uniqueItems is true, no two elements may be equal (including strings). false allows duplicates. Empty and single-element arrays are always valid.

type: array
uniqueItems: true

minContains and maxContains

With contains, minContains (default 1) is the minimum number of elements that must match the contains schema; maxContains caps how many may match.

type: array
contains:
  type: number
minContains: 2

At least two numbers are required somewhere in the array.

type: array
contains:
  type: number
maxContains: 3

At most three elements may be numbers that satisfy contains.

Setting minContains: 0 means the contains constraint is satisfied even when no element matches (the array may have zero matches).

Object Type

The object type validates key-value mappings.

Basic Object Validation

# Schema
type: object

Valid examples:

key: value
another_key: another_value
Sun: 1.9891e30
Jupiter: 1.8986e27
0.01: cm
1: m
1000: km

Invalid examples:

"Not an object"
["An", "array", "not", "an", "object"]

Note: Unlike JSON, YAML allows numeric keys, which are treated as strings.

Properties

# Schema
type: object
properties:
  number:
    type: number
  street_name:
    type: string
  street_type:
    enum: [Street, Avenue, Boulevard]

Valid examples:

number: 1600
street_name: Pennsylvania
street_type: Avenue
number: 1600
street_name: Pennsylvania
{}
number: 1600
street_name: Pennsylvania
street_type: Avenue
direction: NW

Invalid examples:

number: "1600"
street_name: Pennsylvania
street_type: Avenue

Note: By default, leaving out properties is valid, and providing additional properties is also valid.

Pattern Properties

# Schema
type: object
patternProperties:
  ^S_:
    type: string
  ^I_:
    type: integer

Valid examples:

S_25: This is a string
I_0: 42
keyword: value

Invalid examples:

S_0: 42
I_42: This is a string

Additional Properties

By default, additional properties are allowed. You can restrict this:

# Schema
type: object
properties:
  number:
    type: number
  street_name:
    type: string
additionalProperties: false

Valid examples:

number: 1600
street_name: Pennsylvania

Invalid examples:

number: 1600
street_name: Pennsylvania
direction: NW

You can also specify a schema for additional properties:

# Schema
type: object
properties:
  number:
    type: number
additionalProperties:
  type: string

Valid examples:

number: 1600
direction: NW

Invalid examples:

number: 1600
office_number: 201

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
name: William Shakespeare
email: bill@stratford-upon-avon.co.uk
address: Henley Street, Stratford-upon-Avon, Warwickshire, England
authorship: in question

Invalid examples:

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

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

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"

Error: [1:1] .: Property name '-001 invalid' does not match pattern '^[A-Za-z_][A-Za-z0-9_]*$'

Object 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