Skip to content

composition.md

Latest commit

 

History

History
393 lines (319 loc) · 5.23 KB

composition.md

File metadata and controls

393 lines (319 loc) · 5.23 KB
layout default
title Composition
parent Features
nav_order 5

Composition

YAML Schema provides several composition operators that allow you to combine multiple schemas: allOf, anyOf, oneOf, and not.

allOf

The allOf keyword requires that the value validates against all of the provided schemas.

Basic allOf

# Schema
allOf:
  - type: string
    minLength: 1
  - type: string
    maxLength: 5

Valid examples:

"short"

Invalid examples:

""
"too long"

The value must satisfy both constraints: it must be a string with length between 1 and 5 characters.

anyOf

The anyOf keyword requires that the value validates against at least one of the provided schemas.

Basic anyOf

# Schema
anyOf:
  - type: string
    maxLength: 5
  - type: number
    minimum: 0

Valid examples:

"short"
12

Invalid examples:

"too long"
-5
true

The value can be either a short string (5 characters or less) OR a non-negative number.

anyOf with Description

# Schema
description: A string or a number
anyOf:
  - type: string
  - type: number

Valid examples:

"I am a string"
42

Invalid examples:

true

oneOf

The oneOf keyword requires that the value validates against exactly one of the provided schemas (not zero, not multiple).

Basic oneOf

# Schema
oneOf:
  - type: number
    multipleOf: 5
  - type: number
    multipleOf: 3

Valid examples:

10
9

Invalid examples:

2
15

The value 15 is rejected because it's a multiple of both 5 and 3, which means it matches multiple schemas. The value 2 is rejected because it matches none of the schemas.

oneOf with Objects

# 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

oneOf with Null or Object

# Schema
type: object
properties:
  child:
    oneOf:
      - type: null
      - type: object
        properties:
          name:
            type: string
        required:
          - name
additionalProperties: false

Valid examples:

child: null
child:
  name: John

Invalid examples:

name: John

This schema allows child to be either null or an object with a required name property.

oneOf in Properties

# Schema
type: object
properties:
  name:
    type: string
  github:
    type: object
    properties:
      environments:
        type: object
        patternProperties:
          "^[a-zA-Z][a-zA-Z0-9_-]*$":
            type: object
            properties:
              reviewers:
                oneOf:
                  - type: null
                  - type: array
                    items:
                      type: string

Valid examples:

name: test
github:
  environments:
    development:
      reviewers: null
name: test
github:
  environments:
    production:
      reviewers:
        - alice
        - bob

Invalid examples:

name: test
github:
  environments:
    development:
      reviewers: true

oneOf with Pattern Properties

# Schema
type: object
patternProperties:
  ^[a-zA-Z0-9]+$:
    oneOf:
      - type: null
      - type: object
        properties:
          name:
            type: string

Valid examples:

a1b:
  name: John

not

The not keyword requires that the value does not validate against the provided schema.

Basic not

# Schema
not:
  type: string

Valid examples:

42
key: value

Invalid examples:

"I am a string"

not with Constraints

# Schema
not:
  type: number
  multipleOf: 2

Valid examples:

1
-1
3

Invalid examples:

2
-2

This schema accepts any value that is NOT an even number.

Combining Composition Operators

Composition operators can be nested and combined to create complex validation rules:

# Schema
type: object
properties:
  child:
    oneOf:
      - type: null
      - type: object
        properties:
          name:
            type: string
        required:
          - name
additionalProperties: false
# Schema
type: object
properties:
  github:
    type: object
    properties:
      environments:
        type: object
        patternProperties:
          "^[a-zA-Z][a-zA-Z0-9_-]*$":
            type: object
            properties:
              reviewers:
                oneOf:
                  - type: null
                  - type: array
                    items:
                      type: string

These examples show how oneOf can be used within object properties and pattern properties to create flexible schemas that allow multiple valid forms.