Carvel Logo

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/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/desc "DNS domains to accept traffic for."
#@schema/default ["apps.example.com", "mobile.example.com"]
app_domains:
- ""

#@schema/desc "Connection information for databases used by the system."
databases:
- name: ""
  adapter: postgresql
  host: ""
  port: 5432

#@schema/desc "Configuration for experimental/optional components; see documentation for more details."
#@schema/type any=True
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:
          type: object
          additionalProperties: false
          properties:
            enabled:
              type: boolean
              default: true
            static_ip:
              type: string
              default: null
              nullable: true
          description: Whether to include a LoadBalancer type service and if so, what its IP address is.
        app_domains:
          type: array
          items:
            type: string
            default: ""
          default:
          - apps.example.com
          - mobile.example.com
          description: DNS domains to accept traffic for.
        databases:
          type: array
          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: []
          description: Connection information for databases used by the system. 
        additional_config:
          nullable: true
          default: {}
          description: Configuration for experimental/optional components; see documentation for more details.

Exported Properties

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

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

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.

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.

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.

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.