Export Schema in OpenAPI Format

The primary use of schema is to declare (and type-check) Data Values.

ytt also supports the ability to export schema definitions in OpenAPI v3.0.x format. This is useful for tools that require schema definition in this industry-standard format. For example, kapp-controller, requires Package ’s spec.valuesSchema.openAPIv3 to contain an OpenAPI Schema map.

In this way, one can write their schema once and reuse it in situations that require the OpenAPI v3 format.

Working Example ¶

Given a ytt schema:

#! schema.yml

#@data/values-schema
---
#@schema/title "LoadBalancer type service"
#@schema/desc "Whether to include a LoadBalancer type service and if so, what its IP address is."
load_balancer:
  enabled: true
  #@schema/nullable
  static_ip: ""

#@schema/title "DNS domains"
#@schema/desc "DNS domains to accept traffic for."
#@schema/default ["apps.example.com", "mobile.example.com"]
app_domains:
  #@schema/examples ("Example app domain", "web.myapp.com"), ("","localhost:8080")
  - ""

#@schema/title "Database connections"
#@schema/desc "Connection information for databases used by the system."
#@schema/examples ("Example for local db", [{"name": "default", "adapter": "postgresql", "host": "localhost", "port": 8080}])
databases:
- name: ""
  #@schema/validation one_of=["postgresql", "mariadb"]
  adapter: postgresql
  host: ""
  #@schema/desc "Only allow unprivileged ports"
  #@schema/validation min=1024
  port: 5432

#@schema/title "Additional configuration"
#@schema/desc "Configuration for experimental/optional components; see documentation for more details."
#@schema/examples ("Example of additional config", {"username": "default", "password": "password", "insecureFlag": True})
#@schema/type any=True
#@schema/deprecated "This data value will be removed in a future release"
additional_config: {}

One can generate the corresponding OpenAPI Document:

$ ytt -f schema.yml --data-values-schema-inspect --output openapi-v3

where:

--data-values-schema-inspect — after all Data Value Schema files have been processed, print the effective schema (instead of rendering any templates).
--ouput=openapi-v3 — the schema format to use when rendering is OpenAPI v3.0.x (as opposed to ytt formatted schema).

… which yields:

openapi: 3.0.0
info:
  version: 0.1.0
  title: Schema for data values, generated by ytt
paths: {}
components:
  schemas:
    dataValues:
      type: object
      additionalProperties: false
      properties:
        load_balancer:
          title: LoadBalancer type service
          type: object
          additionalProperties: false
          description: Whether to include a LoadBalancer type service and if so, what its IP address is.
          properties:
            enabled:
              type: boolean
              default: true
            static_ip:
              type: string
              nullable: true
              default: null
        app_domains:
          title: DNS domains
          type: array
          description: DNS domains to accept traffic for.
          items:
            type: string
            x-example-description: Example app domain
            example: web.myapp.com
            default: ""
          default:
            - apps.example.com
            - mobile.example.com
        databases:
          title: Database connections
          type: array
          description: Connection information for databases used by the system.
          x-example-description: Example for local db
          example:
            - name: default
              adapter: postgresql
              host: localhost
              port: 8080
          items:
            type: object
            additionalProperties: false
            properties:
              name:
                type: string
                default: ""
              adapter:
                type: string
                default: postgresql
                enum:
                - postgresql
                - mariadb
              host:
                type: string
                default: ""
              port:
                type: integer
                description: Only allow unprivileged ports
                default: 5432
                minimum: 1024
          default: []
        additional_config:
          title: Additional configuration
          nullable: true
          deprecated: true
          description: Configuration for experimental/optional components; see documentation for more details.
          x-example-description: Example of additional config
          example:
            username: default
            password: password
            insecureFlag: true
          default: {}

Exported Properties ¶

Of the properties declared in the OpenAPI Schema specification, the following are generated.

`title` ¶

(As of v0.39.0+)

Sets the user-friendly name or title of the node

when a data value is annotated @schema/title, the value of that title is the value of this property, verbatim;
otherwise, this property is omitted.

`type` ¶

Names the type of the schema.

The value of this property depends on the type of data value implied in the ytt schema:

map ==> object
array ==> array
boolean ==> bool
string ==> string
integer ==> integer
float ==> type: number; format: float

`additionalProperties` ¶

Indicates whether other keys are allowed in a mapping/object.

whenever inspecting a data value that is a map, ytt includes this property, setting it to false;
when a data value is annotated @schema/type any=True, this property is omitted.

`nullable` ¶

Indicates whether null is also allowed.

when a data value is annotated @schema/nullable or @schema/type any=True, this property is included and set to true;
otherwise, this property is omitted.
#@schema/validation not_null= is not supported

`deprecated` ¶

(As of v0.39.0+)

Indicates if a key is deprecated.

when a data value is annotated @schema/deprecated "", this property is included and set to true;
requires a string argument intended to explain the deprecation, this string is omitted from the openapi document.
otherwise, this property is omitted.

`description` ¶

Explains the contents and/or consequences of certain values of the property.

when a data value is annotated @schema/desc, the value of that description is the value of this property, verbatim;
otherwise, this property is omitted.

`x-example-description` ¶

(As of v0.39.0+)

Explains the contents of the example property.

when a data value is annotated @schema/examples, examples are provided via 2-tuples, only the first tuple will be exported to the OpenAPI Document.
the example description is the first argument of 2-tuple, and must be a string.
otherwise, this property is omitted.

`example` ¶

(As of v0.39.0+)

Presents an example value for the data value.

when a data value is annotated @schema/examples, examples are provided via 2-tuples, only the first tuple will be exported to the OpenAPI Document.
a 2-tuple contains string description, and an example value: ("first example", exampleYAML()).
example values should conform to the type of the same property.
otherwise, this property is omitted.

`default` ¶

Declares a default value.

The value of this property:

is always included;
is typically the value of the data value in the ytt schema;
if the data value is annotated @schema/default, that value is used instead.

`minimum` ¶

Represents the min= named validation

only exported if the #@schema/validation min property is present
can be set together with max=
not exported if a when= attribute is present on the validation

`maximum` ¶

Represents the max= named validation

only exported if the #@schema/validation max= property is present
can be set together with min=
not exported if a when= attribute is present on the validation

`minLength` / `minItems` / `minProperties` ¶

Represents the min_len= named validation

only exported if the #@schema/validation min_len= property is present
can be set together with max_len=
not exported if a when= attribute is present on the validation
the name of this property depends on the value type, string = minLength, array = minItems, object = minProperties

`maxLength` / `maxItems` / `maxProperties` ¶

Represents the max_len= named validation

only exported if the #@schema/validation max_len= property is present
can be set together with min_len=
not exported if a when= attribute is present on the validation
the name of this property depends on the value type, string = maxLength, array = maxItems, object = maxProperties

`enum` ¶

Represents the one_of= named validation

only exported if the #@schema/validation one_of=[] property is present
supports string and number values
not exported if a when= attribute is present on the validation

Known Limitations ¶

The following are not yet supported in ytt:

only Named Validation Rules are supported as validations.
custom validation rules using lambda are not supported.
there is no means yet to modify the info section of the OpenAPI document from within a --data-values-schema-inspect. There are defaults supplied, however we recommend that these fields are updated manually.
inspecting output in ytt Schema format is not yet supported.

(Help improve our docs: edit this page on GitHub)

Export Schema in OpenAPI Format

Working Example ¶

Exported Properties ¶

title ¶

type ¶

additionalProperties ¶

nullable ¶

deprecated ¶

description ¶

x-example-description ¶

example ¶

default ¶

minimum ¶

maximum ¶

minLength / minItems / minProperties ¶

maxLength / maxItems / maxProperties ¶

enum ¶

Known Limitations ¶

`title` ¶

`type` ¶

`additionalProperties` ¶

`nullable` ¶

`deprecated` ¶

`description` ¶

`x-example-description` ¶

`example` ¶

`default` ¶

`minimum` ¶

`maximum` ¶

`minLength` / `minItems` / `minProperties` ¶

`maxLength` / `maxItems` / `maxProperties` ¶

`enum` ¶