Skip to content

Latest commit

 

History

History

docs

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 

README.md

Annotations from comments

JSON schema is partially implemented in this tool. It uses line comments to add annotations for the schema because head comments are frequently used by humans and tools like helm-docs. Multiple annotations can be added to a single line separated by semicolon. For example:

nameOverride: "myapp" # @schema maxLength:10;pattern:^[a-z]+$

This will generate following schema:

"nameOverride": {
    "maxLength": 10,
    "type": "string"
}

The following annotations are supported:

Validation Keywords for Any Instance Type

Type

The type keyword is used to restrict a value to a specific primitive type. There are several possible values for type:

  • string
  • number
  • integer
  • boolean
  • object
  • array
  • null

Multiple types

Default behaviour returns always a string unless annotation is used. In that case, it returns array of strings. Useful for keys without any value declared for documentation purposes. section 6.1.1

# -- (int) replica count
replicaCount: # @schema type:[integer, null]
"replicaCount": {
    "type": [
        "integer",
        "null"
    ]
}

Another way to use this is to define type when using anchors and aliases in yaml. See discussion #28 for more details.

app: &app
  settings:
    namespace:
      - *app # @schema type:[string]
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "properties": {
        "app": {
            "properties": {
                "settings": {
                    "properties": {
                        "namespace": {
                            "items": {
                                "type": [
                                    "string"
                                ]
                            },
                            "type": "array"
                        }
                    },
                    "type": "object"
                }
            },
            "type": "object"
        }
    },
    "type": "object"
}

Enum

Always returns array of strings. Special case is null where instead of string, it is treated as valid input type. section 6.1.2

service: ClusterIP # @schema enum:[ClusterIP, LoadBalancer, null]
"service": {
    "enum": [
        "ClusterIP",
        "LoadBalancer",
        null
    ],
    "type": "string"
}

ItemEnum

This is a special key that apply enum on items of an array.

port: [80, 443] # @schema itemEnum:[80, 8080, 443, 8443]
"port": {
    "items": {
        "type": "number",
        "enum": [
            "80",
            "443",
            "8080",
            "8443"
        ]
    },
    "type": [
        "array"
    ]
}

Strings

maxLength

Non-negative integer. section 6.3.1

nameOverride: "myapp" # @schema maxLength:10

This will generate following schema:

"nameOverride": {
    "maxLength": 10,
    "type": "string"
}

minLength

Non-negative integer. section 6.3.1

nameOverride: "myapp" # @schema minLength:3

This will generate following schema:

"nameOverride": {
    "minLength": 3,
    "type": "string"
}

pattern

String that is valid regular expression, according to the ECMA-262 regular expression dialect. section 6.3.3

nameOverride: "myapp" # @schema pattern:^[a-z]+$

This will generate following schema:

"nameOverride": {
    "type": "string"
}

Numbers

multipleOf

Number greater than 0. section 6.2.1

replicas: 2 # @schema multipleOf:2
"replicas": {
    "multipleOf": 2,
    "type": "integer"
}

maximum

Number. section 6.2.2

replicas: 2 # @schema maximum:10
"replicas": {
    "maximum": 10,
    "type": "integer"
}

minimum

Number. section 6.2.4

replicas: 5 # @schema minimum:2
"replicas": {
    "minimum": 2,
    "type": "integer"
}

Arrays

item

Define the item type of empty arrays.

imagePullSecrets: [] # @schema item: object

This will generate following schema:

"imagePullSecrets": {
    "items": {
        "type": "object"
    }
}

maxItems

Non-negative integer. section 6.4.1

dummyList: # @schema maxItems:5
  - "item1"
  - "item2"
  - "item3"
"dummyList": {
    "items": {
        "type": "string"
    },
    "maxItems": 5,
    "type": "array"
}

minItems

Non-negative integer. section 6.4.2

dummyList: # @schema minItems:2
  - "item1"
  - "item2"
  - "item3"
"dummyList": {
    "items": {
        "type": "string"
    },
    "minItems": 2,
    "type": "array"
}

uniqueItems

Boolean. section 6.4.3

dummyList: # @schema uniqueItems:true
  - "item1"
  - "item2"
  - "item3"
"dummyList": {
    "items": {
        "type": "string"
    },
    "type": "array",
    "uniqueItems": true
}

Objects

maxProperties

Non-negative integer. section 6.5.1

nodeSelector: # @schema maxProperties:10
  kubernetes.io/hostname: "my-node"
"nodeSelector": {
    "maxProperties": 10,
    "properties": {
        "kubernetes.io/hostname": {
            "type": "string"
        }
    },
    "type": "object"
}

minProperties

Non-negative integer. section 6.5.2

nodeSelector: # @schema minProperties:1
  kubernetes.io/hostname: "my-node"
"nodeSelector": {
    "minProperties": 1,
    "properties": {
        "kubernetes.io/hostname": {
            "type": "string"
        }
    },
    "type": "object"
}

required

Array of unique strings appended to the parent node. section 6.5.3

image:
  repository: "nginx" # @schema required:true
  tag: "latest" # @schema required:true
  imagePullPolicy: "IfNotPresent"
"image": {
    "properties": {
        "imagePullPolicy": {
            "type": "string"
        },
        "repository": {
            "type": "string"
        },
        "tag": {
            "type": "string"
        }
    },
    "required": [
        "repository",
        "tag"
    ],
    "type": "object"
}

patternProperties

JSON string added "AS IS" to the node. section 10.3.2.2

image: # @schema patternProperties: {"^[a-z]$": {"type": "string"}}
  repository: "nginx"
"image": {
    "patternProperties": {
        "^[a-z]$": {
            "type": "string"
        }
    },
    "properties": {
        "repository": {
            "type": "string"
        }
    },
    "type": "object"
}

additionalProperties

Boolean. section 10.3.2.3

image: # @schema additionalProperties: false
  repository: "nginx"
"image": {
    "additionalProperties": false,
    "properties": {
        "repository": {
            "type": "string"
        }
    },
    "type": "object"
}

Base URI, Anchors, and Dereferencing

$id

String. section 8.2.1

image: # @schema $id: https://example.com/schema.json
  repository: nginx
  tag: latest
  pullPolicy: Always
"image": {
    "$id": "https://example.com/schema.json",
    "properties": {
        "pullPolicy": {
            "type": "string"
        },
        "repository": {
            "type": "string"
        },
        "tag": {
            "type": "string"
        }
    },
    "type": "object"
}

$ref

String. section 8.2.3.1

subchart: # @schema $ref: https://example.com/schema.json
  enabled: true
  name: subchart
  values:
    foo: bar
    bar: baz
"subchart": {
    "$ref": "https://example.com/schema.json",
    "properties": {
        "enabled": {
            "type": "boolean"
        },
        "name": {
            "type": "string"
        },
        "values": {
            "properties": {
                "bar": {
                    "type": "string"
                },
                "foo": {
                    "type": "string"
                }
            },
            "type": "object"
        }
    },
    "type": "object"
}

Meta-Data Annotations

title and description

String. section 9.1

fullnameOverride: bar # @schema title: My title ; description: My description
"fullnameOverride": {
    "title": "My title",
    "description": "My description",
    "type": "string"
},

default

Any JSON value. section 9.2

tolerations: [] # @schema default: [{"key":"foo","operator":"Equal","value":"bar","effect":"NoSchedule"}]
"tolerations": {
    "default": [
        {
            "effect": "NoSchedule",
            "key": "foo",
            "operator": "Equal",
            "value": "bar"
        }
    ],
    "type": "array"
}

readOnly

Boolean. section 9.4

image:
  tag: latest # @schema readOnly: true
"image": {
    "properties": {
        "tag": {
            "readOnly": true,
            "type": "string"
        }
    },
    "type": "object"
}