From f761340b8103ef8cf75b4062054b75d6d1d91b1b Mon Sep 17 00:00:00 2001 From: Pablo Terradillos Date: Thu, 29 Jan 2026 00:08:39 -0300 Subject: [PATCH 1/2] Added docs for fn::conform --- .../syntax/builtin-functions/_index.md | 7 +- .../syntax/builtin-functions/fn-conform.md | 232 ++++++++++++++++++ 2 files changed, 236 insertions(+), 3 deletions(-) create mode 100644 content/docs/esc/environments/syntax/builtin-functions/fn-conform.md diff --git a/content/docs/esc/environments/syntax/builtin-functions/_index.md b/content/docs/esc/environments/syntax/builtin-functions/_index.md index 05f8dbf4dab5..d780e142349d 100644 --- a/content/docs/esc/environments/syntax/builtin-functions/_index.md +++ b/content/docs/esc/environments/syntax/builtin-functions/_index.md @@ -19,14 +19,15 @@ All function invocations take the form of an object with a single key that names ## Functions -- [`fn::fromJSON`](/docs/esc/environments/syntax/builtin-functions/fn-from-json) +- [`fn::concat`](/docs/esc/environments/syntax/builtin-functions/fn-concat) +- [`fn::conform`](/docs/esc/environments/syntax/builtin-functions/fn-conform) - [`fn::fromBase64`](/docs/esc/environments/syntax/builtin-functions/fn-from-base64) +- [`fn::fromJSON`](/docs/esc/environments/syntax/builtin-functions/fn-from-json) - [`fn::join`](/docs/esc/environments/syntax/builtin-functions/fn-join) -- [`fn::split`](/docs/esc/environments/syntax/builtin-functions/fn-split) -- [`fn::concat`](/docs/esc/environments/syntax/builtin-functions/fn-concat) - [`fn::open`](/docs/esc/environments/syntax/builtin-functions/fn-open) - [`fn::rotate`](/docs/esc/environments/syntax/builtin-functions/fn-rotate) - [`fn::secret`](/docs/esc/environments/syntax/builtin-functions/fn-secret) +- [`fn::split`](/docs/esc/environments/syntax/builtin-functions/fn-split) - [`fn::toBase64`](/docs/esc/environments/syntax/builtin-functions/fn-to-base64) - [`fn::toJSON`](/docs/esc/environments/syntax/builtin-functions/fn-to-json) - [`fn::toString`](/docs/esc/environments/syntax/builtin-functions/fn-to-string) diff --git a/content/docs/esc/environments/syntax/builtin-functions/fn-conform.md b/content/docs/esc/environments/syntax/builtin-functions/fn-conform.md new file mode 100644 index 000000000000..b90db13e1661 --- /dev/null +++ b/content/docs/esc/environments/syntax/builtin-functions/fn-conform.md @@ -0,0 +1,232 @@ +--- +title: fn::conform +title_tag: fn::conform +h1: fn::conform +meta_desc: Pulumi ESC allows you to compose and manage hierarchical collections of configuration and secrets and consume them in various ways. +menu: + esc: + parent: esc-syntax-builtin-functions + identifier: esc-syntax-fn-conform + weight: 2 +--- + +The `fn::conform` built-in function validates a value against a JSON Schema. If the value does not conform to the schema, a validation error is raised and the environment cannot be saved until the issues are resolved. + +## Declaration + +```yaml +fn::conform: + schema: json-schema + value: value-to-validate +``` + +### Parameters + +| Property | Type | Description | +|----------|--------|------------------------------------------------------| +| `schema` | object | A JSON Schema definition to validate the value against. +| `value` | any | The value to validate. + +### Returns + +If validation passes, the original `value` is returned. If validation fails, an error is raised and the environment cannot be saved. + +## Example + +### Basic type validation + +#### Definition + +```yaml +values: + valid-string: + fn::conform: + schema: { type: string } + value: "hello" +``` + +#### Evaluated result + +```json +{ + "valid-string": "hello" +} +``` + +### Number constraints + +#### Definition + +```yaml +values: + validated-number: + fn::conform: + schema: { type: number, minimum: 0 } + value: 42 +``` + +#### Evaluated result + +```json +{ + "validated-number": 42 +} +``` + +### Object with required fields + +#### Definition + +```yaml +values: + user: + fn::conform: + schema: + type: object + properties: + name: { type: string } + email: { type: string } + required: [name, email] + value: + name: "Alice" + email: "alice@example.com" +``` + +#### Evaluated result + +```json +{ + "user": { + "name": "Alice", + "email": "alice@example.com" + } +} +``` + +### Dynamic schema from reference + +You can define schemas as values and reference them dynamically: + +#### Definition + +```yaml +values: + my-schema: + type: string + minLength: 1 + validated: + fn::conform: + schema: ${my-schema} + value: "hello" +``` + +#### Evaluated result + +```json +{ + "my-schema": { + "type": "string", + "minLength": 1 + }, + "validated": "hello" +} +``` + +### Array validation + +#### Definition + +```yaml +values: + tags: + fn::conform: + schema: + type: array + items: { type: string } + value: ["production", "us-east-1"] +``` + +#### Evaluated result + +```json +{ + "tags": ["production", "us-east-1"] +} +``` + +### Reusing schemas from imported environments + +You can define schemas in a separate environment and import them for reuse across multiple environments. This allows you to centralize schema definitions and ensure consistent validation. + +#### Schema environment (myproj/schemas) + +```yaml +values: + user-schema: + type: object + properties: + name: { type: string } + email: { type: string } + required: [name, email] +``` + +#### Environment using the imported schema + +```yaml +imports: + - schemas + +values: + user: + fn::conform: + schema: ${user-schema} + value: + name: "Alice" + email: "alice@example.com" +``` + +#### Evaluated result + +```json +{ + "user": { + "name": "Alice", + "email": "alice@example.com" + } +} +``` + +This pattern is useful for enforcing consistent validation rules across teams and projects. + +## Validation errors + +When a value does not conform to its schema, `fn::conform` raises an error that prevents the environment from being saved. This ensures configuration issues are caught before the environment is used. + +### Example: type mismatch + +```yaml +values: + type-error: + fn::conform: + schema: { type: string } + value: 42 +``` + +This raises an error: `expected string, got number`. The environment cannot be saved until the value conforms to the schema. + +### Example: missing required field + +```yaml +values: + missing-required: + fn::conform: + schema: + type: object + properties: + name: { type: string } + required: [name] + value: + other: "value" +``` + +This raises an error indicating that the required field `name` is missing. The environment cannot be saved until the required field is provided. From 78e223f92dda3296297a76e94297de14fcb43124 Mon Sep 17 00:00:00 2001 From: Pablo Terradillos Date: Thu, 29 Jan 2026 12:35:23 -0300 Subject: [PATCH 2/2] suggest using environments built-in property for schemas --- .../syntax/builtin-functions/fn-conform.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/content/docs/esc/environments/syntax/builtin-functions/fn-conform.md b/content/docs/esc/environments/syntax/builtin-functions/fn-conform.md index b90db13e1661..f6ccf4ce47f8 100644 --- a/content/docs/esc/environments/syntax/builtin-functions/fn-conform.md +++ b/content/docs/esc/environments/syntax/builtin-functions/fn-conform.md @@ -154,9 +154,11 @@ values: } ``` -### Reusing schemas from imported environments +### Reusing schemas from other environments -You can define schemas in a separate environment and import them for reuse across multiple environments. This allows you to centralize schema definitions and ensure consistent validation. +You can define schemas in a separate environment and reference them for reuse across multiple environments. This allows you to centralize schema definitions and ensure consistent validation. + +Using the [`environments` built-in property](/docs/esc/environments/syntax/builtin-properties/environments/) to reference the schema is the recommended approach because it doesn't merge the schema into your environment's output. #### Schema environment (myproj/schemas) @@ -170,16 +172,13 @@ values: required: [name, email] ``` -#### Environment using the imported schema +#### Environment using the schema reference ```yaml -imports: - - schemas - values: user: fn::conform: - schema: ${user-schema} + schema: ${environments.myproj.schemas.user-schema} value: name: "Alice" email: "alice@example.com"