Generate Description from `@schema/desc` annotation

[cari-lynn]

As a Configuration Author I want to generate an Openapi description key from my configuration annotations so that Configuration Consumers see what the key's purpose is.

---

:green_circle: Scenario 1: @schema/desc annotation creates a description key for an map

Given the following schema exists

#! schema.yml
#@data/values-schema
---
#@schema/desc "Your beverage of choice"
beverage: juice

When I execute ytt -f schema.yml --data-values-schema-inspect -o openapi-v3 Then I should see on my screen

openapi: 3.0.0
info:
  version: 0.1.0
  title: Openapi schema generated from ytt Data Values Schema
paths: {}
components: 
  schemas:
    dataValues:
      type: object
      additionalProperties: false
      properties:
        beverage:
          description: "Your beverage of choice"
          type: string
          default: juice

---

:green_circle: Scenario 2: @schema/desc annotation creates a description key for an array

Given the following schema exists

#! schema.yml
#@data/values-schema
---
#@schema/desc "Your beverage of choice"
- beverage: juice

When I execute ytt -f schema.yml --data-values-schema-inspect -o openapi-v3 Then I should see a description on the ARRAY

openapi: 3.0.0
info:
  version: 0.1.0
  title: Schema for data values, generated by ytt
paths: {}
components:
  schemas:
    dataValues:
      description: Your beverage of choice  # <-
      type: array
      items:
        type: object
        additionalProperties: false
        properties:
          beverage:
            type: string
            default: juice

---

:green_circle: Scenario 3: @schema/desc annotation creates a description key for an array item

Given the following schema exists

#! schema.yml
#@data/values-schema
---
choice:
-
  #@schema/desc "Your beverage of choice"
  beverage: juice

When I execute ytt -f schema.yml --data-values-schema-inspect -o openapi-v3 Then I should see a description on the MAP

openapi: 3.0.0
info:
  version: 0.1.0
  title: Schema for data values, generated by ytt
paths: {}
components:
  schemas:
    dataValues:
      type: array
      items:
        type: object
        additionalProperties: false
        properties:
          beverage:
            description: Your beverage of choice # <-
            type: string
            default: juice

---

💚 Scenario 4: @schema/desc annotation is added to the description of the schema UPDATED

Given the following schema exists

#! schema.yml
#@data/values-schema
#@schema/desc "Beverage of choice"
---
beverage: juice

When I execute ytt -f schema.yml --data-values-schema-inspect -o openapi-v3 Then no description is added

openapi: 3.0.0
info:
  version: 0.1.0
  title: Openapi schema generated from ytt Data Values Schema
paths: {}
components: 
  schemas:
    dataValues:
      type: object
      additionalProperties: false
      description: Beverage of choice # <---------------------------------------- !! 
      properties:
        beverage:
          type: string
          default: juice

Reasoning for placing the description there instead of in the info object: a Document in ytt is a map, this corresponds to the 'object' under the components.schemas section in the OpenAPI doc. Because of that, annotating a Document should apply that annotation to that level in an OpenAPI Doc.

---

🔴 Scenario 5: When value is any type other than a string

Given the following schema exists

#! schema.yml
#@data/values-schema
---
#@schema/desc 1   # <- integer
beverage: juice

When I execute ytt -f schema.yml --data-values-schema-inspect -o openapi-v3 Then I see an error (similar to overlay errors) that the value must be a string

Map item on line schema.yml:4: Expected 'schema/desc' annotation to have one keyword argument of type string
    in <toplevel>
      schema.yml:4 | beverage: juice

🔴 Scenario 6: When value is any type other than a string

Given the following schema exists

#! schema.yml
#@data/values-schema
---
#@schema/desc "" ""  # <- two string arguments
entree: ham

When I execute ytt -f schema.yml --data-values-schema-inspect -o openapi-v3 Then I see an error (similar to overlay errors) that the value must be one string

Map item on line schema.yml:4: Expected 'schema/desc' annotation to have one keyword argument of type string
    in <toplevel>
      schema.yml:4 | beverage: juice

Excerpt from the proposed Schema documentation

@schema/desc documentation

Sets the text describing the purpose of the node.

• documentation (string) — a more thorough description of the node or section that shares the context of the node, enumerates the range of possible values, explaining the effects of certain value ranges.
  • often these strings include formatting typography (e.g. HTML or Markdown) to support display of these values in documentation settings.
  • per OpenAPI spec, the downstream tooling is likely the responsible party for sanitizing such strings for security.

Links:

• OpenAPI spec

[cari-lynn]

Reviewing this story with the team, got some feedback. Need to update the story to address these questions:

• Should array items be allowed to be annotated?
• should we rename the annotation? (own namespace @doc/desc, or other name @schema/desc)
• should the annotation be able to create the description key in the info object?
• update scenario to not ignore empty string.

done ✅

[pivotaljohn]

re: @schema/desc on a Document Node

Observations:

• other @schema/... annotations on the document map to the properties of components.schema.dataValues.
• the title and description properties are also support/allowed in that set of properties.

Suggestion:

• direct the this metadata to the components.schema.dataValues
• introduce a separate annotation for setting the info section of values (e.g. @schema/info?)

[cari-lynn]

That is a great idea, I created an issue to talk through your suggestion more https://github.com/vmware-tanzu/carvel-ytt/issues/539 @pivotaljohn

[cari-lynn]

Updated the acceptance criteria to change if a data values schema is annotated at the document level:

#@schema/desc ""
---

then it applies to the section immediately following the component.schemas.dataValues section.

[cari-lynn]

Available in v0.38.0