Schema and field reference

Use this reference when you author pattern-metadata.yaml at the repository root or inspect normalized catalog files. The JSON schema defines required and optional fields for catalog format, and the field tables describe how to set identity, links, cluster sizing, and related values in source files. Consult the matching sections before you add or change metadata so validation and documentation sync succeed.

JSON schema overview

The formal schema lives in pattern.schema.json. It applies to normalized catalog files (catalog/<pattern>/pattern.yaml), not necessarily to every field you author in a pattern repository source file.

For how source files are normalized before validation, see Source format and catalog format.

Required fields (catalog format)

After normalization, these top-level fields are required:

Field Type Notes

Field	Type	Notes
`metadata_version`	string	Format `major.minor` (for example, `"1.0"`). Pattern: `^\.[0-9]$`
`name`	string	Lowercase identifier. Pattern: `^[a-z][a-z0-9-]*$`. Must match the repository name.
`pattern_version`	string	Pattern implementation version. Format: `^\.[0-9]$`
`display_name`	string	Human-readable name shown in the UI and documentation.
`repo_url`	string (URI)	Canonical GitHub URL for the pattern repository.
`docs_repo_url`	string (URI)	Documentation repository URL.
`issues_url`	string (URI)	Issue tracker URL.
`docs_url`	string (URI)	Public documentation URL.
`ci_url`	string (URI)	CI dashboard URL for the pattern.
`tier`	string	One of: `maintained`, `tested`, `sandbox`
`owners`	array of strings	At least one GitHub username. Source files can use a comma-separated string; the catalog converts it to an array.
`requirements`	object	Must include `hub`. Can include `spoke`. See Cluster sizing fields.
`extra_features`	object	Must include `hypershift_support` and `spoke_support` (both boolean).
`org`	string	GitHub organization name. Added by the catalog generator; do not add manually to source files.

metadata_version

string

Format major.minor (for example, "1.0"). Pattern: ^\.[0-9]$

name

string

Lowercase identifier. Pattern: ^[a-z][a-z0-9-]*$. Must match the repository name.

pattern_version

string

Pattern implementation version. Format: ^\.[0-9]$

display_name

string

Human-readable name shown in the UI and documentation.

repo_url

string (URI)

Canonical GitHub URL for the pattern repository.

docs_repo_url

string (URI)

Documentation repository URL.

issues_url

string (URI)

Issue tracker URL.

docs_url

string (URI)

Public documentation URL.

ci_url

string (URI)

CI dashboard URL for the pattern.

tier

string

One of: maintained, tested, sandbox

owners

array of strings

At least one GitHub username. Source files can use a comma-separated string; the catalog converts it to an array.

requirements

object

Must include hub. Can include spoke. See Cluster sizing fields.

extra_features

object

Must include hypershift_support and spoke_support (both boolean).

org

string

GitHub organization name. Added by the catalog generator; do not add manually to source files.

Optional fields (catalog format)

Field Type Notes

Field	Type	Notes
`description`	string	Short pattern summary. Recommended for UI catalog cards.
`logo`	string (URI)	Pattern logo URL.
`external_requirements`	object or null	External infrastructure notes. See External requirements fields.
`clustergroupname`	string	Default cluster group for install flows. Added from `values-global.yaml` by the catalog generator.
`variants`	array	Deployment variants. Each entry requires `name`; `default` and `description` are optional.
`spoke`	null	Reserved for future use. Catalog sets this to `null`.

description

string

Short pattern summary. Recommended for UI catalog cards.

logo

string (URI)

Pattern logo URL.

external_requirements

object or null

External infrastructure notes. See External requirements fields.

clustergroupname

string

Default cluster group for install flows. Added from values-global.yaml by the catalog generator.

variants

array

Deployment variants. Each entry requires name; default and description are optional.

spoke

null

Reserved for future use. Catalog sets this to null.

The schema sets additionalProperties: false at the top level and on most nested objects. Do not add undeclared fields to catalog files.

Identity fields (source file)

Field Required in source Description

Field	Required in source	Description
`metadata_version`	Recommended	Schema version for the metadata file (for example, `"1.0"` or `"2.0"`).
`name`	Yes	Pattern directory and repository name. Use lowercase letters and dashes (for example, `multicloud-gitops`). Must match `values-global.yaml` → `global.pattern`.
`display_name`	Yes	Human-readable pattern name (for example, `Multicloud Gitops`).
`description`	Recommended	Short description of the pattern purpose. Displayed in the UI catalog.
`pattern_version`	Yes	Version of the pattern implementation (for example, `"1.0"`).

metadata_version

Recommended

Schema version for the metadata file (for example, "1.0" or "2.0").

name

Yes

Pattern directory and repository name. Use lowercase letters and dashes (for example, multicloud-gitops). Must match values-global.yaml → global.pattern.

display_name

Yes

Human-readable pattern name (for example, Multicloud Gitops).

description

Recommended

Short description of the pattern purpose. Displayed in the UI catalog.

pattern_version

Yes

Version of the pattern implementation (for example, "1.0").

Link and governance fields (source file)

Field Required in source Description

Field	Required in source	Description
`repo_url`	Yes	Canonical GitHub URL (for example, `https://github.com/validatedpatterns/multicloud-gitops`). The docs sync workflow verifies this matches the repository running the workflow.
`docs_repo_url`	Yes	GitHub URL for the documentation repository, typically `https://github.com/validatedpatterns/docs`.
`issues_url`	Yes	GitHub issues URL for the pattern repository.
`docs_url`	Yes	Public URL on validatedpatterns.io (for example, `https://validatedpatterns.io/patterns/multicloud-gitops/`).
`ci_url`	Yes	CI dashboard URL (for example, `https://validatedpatterns.io/ci/?pattern=mcgitops`).
`logo`	Optional	Logo URL for the UI catalog and website.
`tier`	Yes	One of `sandbox`, `tested`, or `maintained`. For definitions, see About pattern tiers.
`owners`	Yes	GitHub usernames responsible for the pattern. Use a comma-separated string (`user1, user2`) or a YAML list. The catalog normalizes strings to arrays.

repo_url

Yes

Canonical GitHub URL (for example, https://github.com/validatedpatterns/multicloud-gitops). The docs sync workflow verifies this matches the repository running the workflow.

docs_repo_url

Yes

GitHub URL for the documentation repository, typically https://github.com/validatedpatterns/docs.

issues_url

Yes

GitHub issues URL for the pattern repository.

docs_url

Yes

Public URL on validatedpatterns.io (for example, https://validatedpatterns.io/patterns/multicloud-gitops/).

ci_url

Yes

CI dashboard URL (for example, https://validatedpatterns.io/ci/?pattern=mcgitops).

logo

Optional

Logo URL for the UI catalog and website.

tier

Yes

One of sandbox, tested, or maintained. For definitions, see About pattern tiers.

owners

Yes

GitHub usernames responsible for the pattern. Use a comma-separated string (user1, user2) or a YAML list. The catalog normalizes strings to arrays.

Cluster sizing fields

The requirements section records the Red Hat OpenShift Container Platform cluster configurations that a pattern team has tested. Set these values to match configurations you have validated in CI or reference deployments. For alignment checks, see Alignment checks for contributors.

For operators, these values provide a reference starting point for cluster planning. They appear in generated cluster sizing documentation and in the UI catalog. They do not represent Red Hat OpenShift Container Platform platform minimums and do not guarantee successful deployment or operation in every environment. Smaller clusters might work for limited demos; larger clusters are often required for production workloads or higher user concurrency.

Meeting the documented replica counts and instance types does not guarantee success. Your results depend on workload, scale, optional components, and platform constraints. Use external_requirements.cluster_sizing_note for pattern-specific sizing caveats. For Red Hat OpenShift Container Platform platform install requirements, see Installing OpenShift Container Platform.

Pattern repositories and the UI catalog represent the same sizing data in two shapes. The catalog generator removes the optional platform wrapper during normalization. For more information about normalization, see Source format and catalog format.

Source format nesting

In pattern repositories, nest cloud providers under a platform key:

requirements:
  hub:
    compute:
      platform:
        aws:
          replicas: 3
          type: m5.2xlarge
    controlPlane:
      platform:
        aws:
          replicas: 3
          type: m5.xlarge

Catalog format nesting

After normalization, cloud providers appear directly under compute and controlPlane. The catalog generator removes the platform key:

Path in source file Path in catalog

Path in source file	Path in catalog
`requirements.hub.compute.platform.aws`	`requirements.hub.compute.aws`
`requirements.hub.controlPlane.platform.aws`	`requirements.hub.controlPlane.aws`

requirements.hub.compute.platform.aws

requirements.hub.compute.aws

requirements.hub.controlPlane.platform.aws

requirements.hub.controlPlane.aws

Cluster roles and node pools

hub — Required. Primary cluster (hub or datacenter).
spoke — Optional. Managed or edge clusters imported through Red Hat Advanced Cluster Management (RHACM).

Under each cluster role:

compute — Worker node requirements.
controlPlane — Control plane node requirements.

Under each node pool, define one or more cloud keys (aws, azure, gcp). Each cloud entry requires:

replicas — Integer ≥ 0.
type — Cloud instance type string (for example, m5.2xlarge).

Set worker replicas to 0 when a cluster role uses control plane nodes only.

Extra features

The extra_features object requires both keys when present:

Field Type Description

Field	Type	Description
`hypershift_support`	boolean	Whether the pattern supports Red Hat OpenShift Container Platform hosted control planes (HyperShift).
`spoke_support`	boolean	When `true`, documentation cluster sizing templates include a spoke section.

hypershift_support

boolean

Whether the pattern supports Red Hat OpenShift Container Platform hosted control planes (HyperShift).

spoke_support

boolean

When true, documentation cluster sizing templates include a spoke section.

External requirements fields

Use external_requirements for infrastructure outside the cluster that affects deployment or sizing.

Field Type Description

Field	Type	Description
`cluster_sizing_note`	string	Free-text note displayed in documentation and as an "Additional requirements" tooltip in the UI catalog.

cluster_sizing_note

string

Free-text note displayed in documentation and as an "Additional requirements" tooltip in the UI catalog.

Set external_requirements: to null or leave it empty when you have no external requirements.

Variants field

The optional variants list describes named deployment topologies (for example, hub and standalone).

Field Required Description

Field	Required	Description
`name`	Yes	Short variant identifier.
`description`	Optional	What the variant deploys.
`default`	Optional	Boolean. Set to `true` for the default variant.

name

Yes

Short variant identifier.

description

Optional

What the variant deploys.

default

Optional

Boolean. Set to true for the default variant.

When variants is defined in catalog metadata, the Validated Patterns Operator install flow displays a variant selector with each entry’s name and description. The default variant is pre-selected when default: true is set on one entry. The documentation sync workflow does not render variant lists on validatedpatterns.io. Variants remain available for QE and other tooling that reads pattern-metadata.yaml directly.

For complete YAML examples, see Example metadata files.