provide schema for flow template #592
Description
Problem
Spot the error from this real use case. It took a bit of time for us newbies.
version: 1
trial:
attestations:
- name: jira-ticket
type: jira
- name: risk-level-assessment
type: generic
artifacts:
- name: backend
attestations:
- name: unit-tests
type: junit
- name: security-scan
type: snyk
- name: frontend
attestations:
- name: manual-ui-test
type: generic
- name: coverage-metrics
type: custom:coverage-metricsAnd the failure wasn't much clearer (only in hindsight). When run:
kosli create flow myTrail \
--description myTrailDescription \
--template-file template.yaml
Error: Input payload validation failed: map[trail.atttestations:Extra inputs are not permitted [input: [{'name': 'jira-ticket', 'type': 'jira'}, {'name': 'risk-level-assessment', 'type': 'generic'}]]]Solution
Provide a json schema for immediate validation, autocompletion and documentation, like below:
Click to expand
flow-template.json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Kosli Flow Template",
"description": "Schema for Kosli flow template specification",
"type": "object",
"required": ["version"],
"additionalProperties": false,
"examples": [
{
"version": 1,
"trail": {
"attestations": [
{
"name": "jira-check",
"type": "jira"
}
],
"artifacts": [
{
"name": "frontend-app",
"attestations": [
{
"name": "pull-request-approved",
"type": "pull_request"
},
{
"name": "unit-tests",
"type": "junit"
},
{
"name": "security-scan",
"type": "snyk"
}
]
},
{
"name": "backend-api",
"attestations": [
{
"name": "code-review",
"type": "pull_request"
},
{
"name": "integration-tests",
"type": "junit"
}
]
}
]
}
}
],
"properties": {
"version": {
"type": "integer",
"description": "The version of the specification schema. Allowed values are [1].",
"enum": [1]
},
"trail": {
"type": "object",
"description": "The trail specification",
"additionalProperties": false,
"properties": {
"attestations": {
"type": "array",
"description": "What attestations are required for the trail to be compliant",
"items": {
"type": "object",
"required": ["name", "type"],
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "The attestation name",
"examples": [
"jira-check",
"security-review"
]
},
"type": {
"type": "string",
"description": "The attestation type",
"enum": [
"generic",
"jira",
"junit",
"pull_request",
"snyk",
"sonar",
"*"
]
}
}
}
},
"artifacts": {
"type": "array",
"description": "What artifacts are expected to be produced in the trail",
"items": {
"type": "object",
"required": ["name"],
"additionalProperties": false,
"defaultSnippets": [
{
"label": "New artifact",
"body": {
"name": "${1:artifact-name}",
"attestations": [
{
"name": "${2:attestation-name}",
"type": "${3|generic,jira,junit,pull_request,snyk,sonar|}"
}
]
}
}
],
"properties": {
"name": {
"type": "string",
"description": "Reference name for the artifact (e.g. frontend-app)",
"examples": [
"frontend-app",
"backend-api",
"mobile-app",
"database-migration"
]
},
"attestations": {
"type": "array",
"description": "What attestations are required for the artifact to be compliant",
"items": {
"type": "object",
"required": ["name", "type"],
"additionalProperties": false,
"defaultSnippets": [
{
"label": "New attestation",
"body": {
"name": "${1:attestation-name}",
"type": "${2|generic,jira,junit,pull_request,snyk,sonar|}"
}
}
],
"properties": {
"name": {
"type": "string",
"description": "The attestation name",
"examples": [
"pull-request-approved",
"unit-tests",
"security-scan",
"code-coverage"
]
},
"type": {
"type": "string",
"description": "The attestation type",
"pattern": "^(generic|jira|junit|pull_request|snyk|sonar|custom:.+)$"
}
}
}
}
}
}
}
}
}
}
}Option A: Just document
Add the schema to Flow Template Specification
Guide e.g. VS Code users to place it in a repo (e.g. schemas/flow-template.json) and have .vscode/settings.json define:
{
"yaml.schemas": {
"./schemas/flow-template.json": [
"flow-template.yaml",
"*-flow-template.yaml",
"flow-template-*.yaml",
"**/flow-template.yaml",
"**/*-flow-template.yaml"
]
}
}Option B: Better DevEx
Add the schema to the JSON Schema Store following their Contributing Guide as:
"Any schema on SchemaStore.org will automatically be synchronized to the supporting editors."
Example
