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: ""
  adapter: postgresql
  host: ""
  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
              host:
                type: string
                default: ""
              port:
                type: integer
                default: 5432
          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.

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.

Known Limitations ¶

The following are not yet supported in ytt:

• ytt schema does not yet support declarative validations and thus does not produce such validations in an OpenAPI export.
• 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.