The joomiz.yaml schema

For feature teams and platform teams. The control plane publishes one JSON Schema that describes what a joomiz.yaml file may say. An editor reads it to help you write the file. This page says where to get it, what it holds and what it leaves to joomiz validate.

Get the schema

The call is GET /schema. It needs no token. The answer is a JSON Schema document of the draft-07 dialect, with the content type application/schema+json:

curl -s -D - -o schema.json "$JOOMIZ_SERVER_URL/schema"

HTTP/1.1 200
Content-Type: application/schema+json

The control plane composes the document from its catalog of types every time you ask. A type that your platform offers today is in the document today. Two platforms can give two different documents. The document is large, so this page shows only parts of it.

What the document holds

The top of the document. This is cut: the long description is left out, and the spaces around the colons are tidied.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "joomiz.yaml",
  "type": "object",
  "additionalProperties": false,
  "required": ["application"],
  ...

These are the keys of the top level, with jq:

jq -c 'keys' schema.json

["$schema","additionalProperties","definitions","description","properties","required","title","type","x-joomiz-catalogs"]

The key properties has the sections of the file, and definitions has the shapes that the sections share:

jq -c '.properties | keys' schema.json

["application","artifacts","environments","tooling","version"]

The schema covers:

Which keys each section may have. A key that the schema does not list is an error. The two maps that hold names that you choose are open: metadata and env.
The kinds of the values, and their bounds, such as the longest text.
The type values that each list accepts, and the shape of the spec of each type. A spec is checked against the entry of its type.
The environments section. It is a mapping keyed by the name of an environment, and not a list.

This is the section environments:

{
  "type": "object",
  "maxProperties": 25,
  "propertyNames": {
    "$ref": "#/definitions/identifier"
  },
  "additionalProperties": {
    "$ref": "#/definitions/environment"
  },
  "description": "A mapping keyed by environment name, not a list."
}

The types of your platform

The key x-joomiz-catalogs lists the types of each category, with the schema of the spec and of the outputs of each. This command lists the names:

jq -c '."x-joomiz-catalogs" | map_values(keys)' schema.json

{"tool":["checkmarx","renovate"],"artifact":["container-image","jar","kong-oas"],"target":["cloud-foundry-space","kong-gateway","kubernetes-namespace"],"deployment":["cloud-foundry-app","kong-api","kubernetes-deployment"],"managed-resource":["azure-key-vault","postgres"],"consumed-resource":["kafka-topic","splunk-index"]}

Your platform can show other types. The types you can request explains how to choose one, and Own the catalog of types shows how a platform team reads an entry.

Keys that start with x-joomiz

Some keys in the document are not part of JSON Schema. A tool that follows the standard ignores them. The Joomiz extension for VS Code reads them.

Key	What it holds
`x-joomiz-catalogs`	The types of each category, with the schema of their `spec` and `outputs`.
`x-joomiz-compatible-resources`	On each type: the types that it may name as its artifact and as its target.
`x-joomiz-ref`	On the `artifact` and `target` of a deployment: the place in the file that the value must name, for example `artifacts[].id`.
`x-joomiz-sensitive`	On an output: the value is the address of a stored secret, and never the secret.

This is the artifact of a deployment. The description is cut:

{
  "type": "string",
  "maxLength": 255,
  "pattern": "^(?!-)(?!.*--)[a-z0-9-]*[a-z0-9]$",
  "description": "The id of an `artifacts[]` entry declared in this same file. Shape onl...",
  "x-joomiz-ref": {
    "up": 5,
    "path": [
      "artifacts",
      "[]",
      "id"
    ],
    "kind": "artifact"
  }
}

What the schema leaves to validate

A schema describes the shape of one document. It cannot compare two parts of the document. So the schema does not check:

That the artifact of a deployment names an artifact that the file declares.
That the target of a deployment names a target of the same environment.
That the two types fit each other.
That an id is used once in a list.
That a ${{ ... }} reference names something that exists.

joomiz validate checks these, except a repeated id in artifacts. joomiz register refuses that one. validate also checks the application against your control plane. The Joomiz extension for VS Code checks the references while you type. Check your file shows validate, and Set up your editor shows the extension.

Use the schema

In an editor. An editor that supports the setting yaml.schemas can read the address of the schema directly. The answer is a bare schema document, with no wrapper around it. Set the address <your control plane>/schema for files that are named joomiz.yaml. Do not use this together with the Joomiz extension, or each problem shows twice.
In a job. To check a file in a pipeline, run joomiz validate. It covers more than the schema. If you must use another tool, fetch the schema at the start of each job, because it changes when the catalog changes. Convert the YAML file to JSON, and check it against the document with a validator for draft-07.
To list the types. Use the commands on this page with jq.