From 5fa7bda923d50f5f31608564d0f950f1db3c4c90 Mon Sep 17 00:00:00 2001 From: Rifa Achrinza <25147899+achrinza@users.noreply.github.com> Date: Mon, 13 Jul 2026 01:18:45 +0800 Subject: [PATCH 1/3] feat: initial job property validation docs Document BOSH release job property validation see: https://github.com/cloudfoundry/community/pull/1049 see: https://github.com/cloudfoundry/bosh-cli/pull/681 see: https://github.com/cloudfoundry/bosh/pull/2602 Signed-off-by: Rifa Achrinza <25147899+achrinza@users.noreply.github.com> --- content/jobs.md | 71 ++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 65 insertions(+), 6 deletions(-) diff --git a/content/jobs.md b/content/jobs.md index 000acc12..4b44815f 100644 --- a/content/jobs.md +++ b/content/jobs.md @@ -18,7 +18,7 @@ Jobs are typically OS specific (Windows vs Linux); however, structure of a job r Spec file defines job metadata. It will be interpreted by the Director when the release is uploaded and when it's deployed. -```yaml +```yaml title="jobs/http-server/spec" --- name: http-server @@ -97,17 +97,76 @@ Schema: Default is `nil`. !!! Note + Within a property definition, `default` is used by the Director, and - `description`, `default` and `example` are displayed by the - [release index](/releases/). In turn, other keys like `type` are used only - for convenience, like Concourse does `env` keys in the - [“web” job definition][concourse_web_spec]. Indeed, the schema is not - formally validated by the Director when registering a release job. + `description`, `default` and `example` are displayed by the [release + index](/releases/). In turn, other keys like `type` are used only for + convenience, like Concourse does `env` keys in the [“web” job + definition][concourse_web_spec]. For formal validation by the Director + when registering a release job, see [property + validation](#property-validation). [concourse_web_spec]: https://github.com/concourse/concourse-bosh-release/blob/8d2cfa0/jobs/web/spec#L68-L71 --- +## Property validation {: #property-validation } + +!!! note + + Requires BOSH CLI + [v7.9.1](https://github.com/cloudfoundry/bosh-cli/releases/tag/v7.9.1)+ + when creating a release and BOSH Director + [v280.1.22](https://github.com/cloudfoundry/bosh/releases/tag/v280.1.22)+ + when deploying. The schema file is ignored on earlier versions. + +!!! note + + `bosh create-env` does not perform property validation. + +The `properties` defined in a release job `spec` file can be associated with a +JSON Schema instance to enable validation during BOSH deployments. + +Release authors can add a `properties-schema.json` file at the root directory +of each job they'd like to add property validation to: + +```json title="jobs/http-server/properties-schema.json" +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "listen_port": { + "type": "integer", + "minimum": 1, + "maximum": 65535 + } + } +} +``` +### BOSH-specific extensions + +BOSH extends JSON Schema with a custom `certificate` type, which can be used +to validate for PEM-encoded x509 v3 certificates: + +```json title="jobs/http-server/properties-schema.json" +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "trusted_certificate": { + "type": "certificate" + } + } +} +``` + +!!! note + + The schema is only used for property validation. It does not influence + defaults nor [variable generation](variable-types.md) by the Director's + config server such as CredHub. + +--- ## Templates (ERB configuration files) {: #templates } Release authors can define zero or more templates for each job, but typically From c1e9d04e512f09785881c22d6375fdfa21cc28c2 Mon Sep 17 00:00:00 2001 From: Rifa Achrinza <25147899+achrinza@users.noreply.github.com> Date: Tue, 14 Jul 2026 00:23:59 +0800 Subject: [PATCH 2/3] fix: apply copilot suggestions Signed-off-by: Rifa Achrinza <25147899+achrinza@users.noreply.github.com> --- content/jobs.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/jobs.md b/content/jobs.md index 4b44815f..882cb532 100644 --- a/content/jobs.md +++ b/content/jobs.md @@ -126,10 +126,10 @@ Schema: The `properties` defined in a release job `spec` file can be associated with a JSON Schema instance to enable validation during BOSH deployments. -Release authors can add a `properties-schema.json` file at the root directory +Release authors can add a `properties_schema.json` file at the root directory of each job they'd like to add property validation to: -```json title="jobs/http-server/properties-schema.json" +```json title="jobs/http-server/properties_schema.json" { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", @@ -146,9 +146,9 @@ of each job they'd like to add property validation to: ### BOSH-specific extensions BOSH extends JSON Schema with a custom `certificate` type, which can be used -to validate for PEM-encoded x509 v3 certificates: +to validate for PEM-encoded X.509 v3 certificates: -```json title="jobs/http-server/properties-schema.json" +```json title="jobs/http-server/properties_schema.json" { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", From 4c4455f8e8bd4a9aa3cf36333d4a0d5ebbdf6bea Mon Sep 17 00:00:00 2001 From: Rifa Achrinza <25147899+achrinza@users.noreply.github.com> Date: Sun, 19 Jul 2026 16:56:31 +0800 Subject: [PATCH 3/3] fix: clarify property validation - Document restriction to Draft 2020-12 - Explain zero-string validity for `type: "certificate"` - Fix incorrect `JSON Schema instance` to `JSON Schema document` Signed-off-by: Rifa Achrinza <25147899+achrinza@users.noreply.github.com> --- content/jobs.md | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/content/jobs.md b/content/jobs.md index 882cb532..341bc3a2 100644 --- a/content/jobs.md +++ b/content/jobs.md @@ -124,7 +124,8 @@ Schema: `bosh create-env` does not perform property validation. The `properties` defined in a release job `spec` file can be associated with a -JSON Schema instance to enable validation during BOSH deployments. +JSON Schema (draft 2020-12) document to enable Director-enforced validation +during BOSH deployments. Release authors can add a `properties_schema.json` file at the root directory of each job they'd like to add property validation to: @@ -146,9 +147,9 @@ of each job they'd like to add property validation to: ### BOSH-specific extensions BOSH extends JSON Schema with a custom `certificate` type, which can be used -to validate for PEM-encoded X.509 v3 certificates: +to validate for parseable PEM-encoded X.509 v3 certificates: -```json title="jobs/http-server/properties_schema.json" +```json title="jobs//properties_schema.json" { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", @@ -160,6 +161,22 @@ to validate for PEM-encoded X.509 v3 certificates: } ``` +Zero-length strings are valid for the `certificate` type. To require at least +one parseable PEM certificate, use `minLength`: + +```json title="jobs//properties_schema.json" +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "trusted_certificate": { + "type": "certificate", + "minLength": 1 + } + } +} +``` + !!! note The schema is only used for property validation. It does not influence