Validator v1
This validator provides authors with the ability to structure templates that allow users to select numerous IBM services and artefacts for their toolchains. Validator-v1 is used extensively in IBMs curated templates and these provide good reference material for authors. It employs a hierarchical structure of property types (v-type) which is being extended regularly as more complex templates emerge.
There are two validator phases that are triggered by separate api calls originating from template form schema:
-
Populate: This phase fetches any drop-down list information that can aid the user in the completion of the form. It can utilise any already entered information to do this, such as api-keys, regions etc.
-
Validate: This phase validates the user entered information and returns any errors for display on the form.
To use validator-v1 the following must be added to the form section in your schema file. An example schema file using validator-v1 can be found here.
"form": [{
"type": "validator",
"url": "/devops/validator/validator-v1.html"
}
A validator object should be added to each property (in the properties object) that requires validator support.
"dev-cluster-name": {
"description": {
"$ref": "#/messages/deploy.cluster"
},
"type": "string",
"pattern": "\\S",
"validator": {
"v-type": "k8s-cluster-name",
"params": [
"dev-resource-group",
"dev-region"
]
}
}
| Property | Description |
|---|---|
| v-type | The type of the property to be populated/validated. |
| params | List of other properties that must be fulfilled before this property can be evaluated. In the example above dev-cluster-name cannot be evaluated until dev-resource-group and dev-region have been fulfilled. Also the fulfilled params are used as inputs to the dev-cluster-name population/validation process which results in a filtered dev-cluster-name list being presented to end users. |
| validate | Should the validate process be executed for this property. It should be set to false if the user is allowed to enter a new value that does not appear in the populated list. If omitted this property defaults to true. |
The section lists the various v-types and the input params that each one requires.
| v-type | Description | Params |
|---|---|---|
| api-key | IBM cloud API key or an API key bound to an IAM Service ID. Used for accessing IBM cloud services. Some v-types can optionally accept api-key as a param. For these types if api-key is not specified then the artefacts related to the logged-in users account are retrieved. |
None |
| service‑id‑api‑key | Specifically an API key bound to an IAM Service ID. Used for accessing IBM cloud services. | None |
| resource-group | User resource groups. | *api‑key |
| k8s-region | Kubernetes region. | *api-key |
| k8s-cluster-name | Kubernetes cluster name. | [k8s-region, cf-region, cr-region, kp-region, sm-region, resource-group] |
| cf-region | Cloud Foundry region. | *api-key |
| cf-org | Cloud Foundry organisation. | [k8s-region, cf-region, cr-region, kp-region, sm-region] |
| cf-space | Cloud Foundry space. | cf-org |
| cr-region | Container Registry region. | *api-key |
| k8s‑registry‑namespace | Container registry namespace. | [k8s-region, cf-region, cr-region, kp-region, sm-region] |
| kp-region | Key Protect region. | *api-key |
| kp-instance | Key Protect service instance. | [k8s-region, cf-region, cr-region, kp-region, sm-region], resource-group |
| sm-region | Secrets Manager region. | *api-key |
| sm-instance | Secrets Manager service instance. | [k8s-region, cf-region, cr-region, kp-region, sm-region], resource-group |
| appconfig-region | AppConfig region. | *api-key |
| appconfig-instance | AppConfig instance. | appconfig-region, resource-group |
| vpc-region | Virtual Private Cloud region. | *api-key |
| vpc-name | Virtual Private Cloud name. | vpc-region |
| vpc-instance-group | Virtual Private Cloud instance group. | vpc-name |
| vsi-instance | Virtual Server Instance. | vpc-name |
| alb-instance | Application Load Balancer instance. | vpc-region |
| alb-pool | Application Load Balancer pool. | alb-instance |
| tc-region | Toolchain region. | *api-key |
| toolchain-instance | Toolchain service instance. | *api-key, *tc-region, *resource-group |
| integration-name | Placeholder for the integration name which can act as an input param to other v-types. |
None |
| intergation-status | The status of a Key Protect or Secrets Manager service instance. Should only be used with the status control. |
resource-group, [kp-region, sm-region], [kp-instance, sm-instance], integration-name |
| private-worker-queue-id | A private worker queue identifier. | service-id-api-key |
| gpg-private-key | Used to validate a GPG key. | None |
a, b, c = a, b and c are all required.
*a = a is optional.
[a,b,c] = any combination of a, b or c but a param definition should only contain one region type.
The following is an excerpt from the Key Protect integration definition which uses validator-v1:
"parameters": {
"$schema": "http://json-schema.org/draft-04/schema#",
"properties": {
"name": {
"description": "Enter a name for this tool integration. This name is displayed on your toolchain.",
"title": "Name",
"type": "string",
"validator": {
"v-type": "integration-name"
}
},
"region": {
"description": "Region",
"title": "Region",
"type": "string",
"validator": {
"v-type": "kp-region"
}
},
"resource-group": {
"description": "Resource group",
"title": "Resource group",
"type": "string",
"validator": {
"v-type": "resource-group"
}
},
"instance-name": {
"description": "Service name",
"title": "Service name",
"type": "string",
"pattern": "\\S",
"validator": {
"v-type": "kp-instance",
"params": ["resource-group", "region"]
}
},
"integration-status": {
"type": "string",
"validator": {
"v-type": "integration-status",
"params": ["resource-group", "region", "instance-name", "name"]
}
}
},
"required": ["name", "region", "resource-group", "instance-name"],
"form": [{
"type": "validator",
"url": "/devops/validator/validator-v1.html"
},
{
"type": "status",
"key": "integration-status"
},
"name",
{
"type": "table",
"columnCount": 3,
"widths": ["50%", "3%", "47%"],
"items": [{
"type": "label",
"title": "Region"
}, {
"type": "label",
"title": ""
}, {
"type": "label",
"title": "Resource group"
}, {
"type": "select",
"key": "region"
}, {
"type": "label",
"title": ""
}, {
"type": "select",
"key": "resource-group"
}]
}, {
"type": "select",
"key": "instance-name",
"readonly": false
}
],
"hidden": {
"setup": ["integration-status"],
"create": ["integration-status"]
}
}
The properties section defines the different property types that are required to configure the Key Protect integration and the relationship between them. The form section defines what controls are used to render each property and the general layout of the page.
You can see from the property objects that region and resource-group are input params to instance-name and when the user changes either input param the instance-name dropdown will be filtered accordingly. Also resource-group, region, instance-name and name are input params to the integration-status property, meaning that the status will not be evaluated until all these input params are present. Also, note that integration-status is hidden in the setup and create phases and will only be displayed when an existing integration is opened.
The above configuration yields the following form:
To upgrade your validator to validator-v1 you must change the url of the form.validator object to /devops/validator/validator-v1.html. Then for each property that requires validation support you should add a validator object defining it's v-type and input params.
See adding the validator to your schema for more information.