Validation and troubleshooting

Validate pattern-metadata.yaml before you publish a pattern so the UI catalog and documentation sync workflows accept your changes. Use the schema checks, inclusion rules, and alignment checks in this topic to confirm that required fields and URLs are correct. When a pattern is missing from the catalog or a sync workflow fails, use the troubleshooting steps to identify and fix the cause.

Catalog schema validation

The pattern-ui-catalog repository validates normalized catalog files:

git clone https://github.com/validatedpatterns/pattern-ui-catalog.git
cd pattern-ui-catalog
make generate-catalog    # requires gh, yq, jq, and GitHub authentication
make schema-validate     # requires check-jsonschema (pip install check-jsonschema)

The make schema-validate target checks the following files:

catalog/catalog.yaml against catalog.schema.json
Each catalog/*/pattern.yaml against pattern.schema.json

The pattern-ui-catalog CI pipeline also runs yamllint on generated catalog files.

Documentation sync validation

The docs metadata workflow (.github/workflows/metadata-docs.yml) validates the following conditions:

repo_url in pattern-metadata.yaml matches https://github.com/<org>/<repo>; for the repository running the workflow
The YAML file parses successfully (by using yq and flatten_yaml.rb)

If validation fails, the workflow exits with an error and no pull request is opened. For workflow setup, see Enabling automatic sync to the documentation repository.

Catalog inclusion rules

A pattern repository is included in the UI catalog only when:

The repository is public and tagged with ui-catalog-enabled
pattern-metadata.yaml exists on the default branch
The file parses and normalizes without error

Repositories missing metadata or with invalid YAML are skipped silently during catalog generation.

Alignment checks for contributors

Keep these values consistent across systems:

name matches the Git repository name and global.pattern in values-global.yaml
repo_url matches the actual GitHub repository URL
tier, docs_url, and ci_url align with Hugo frontmatter and CI badge JSON (see Testing artifacts)
requirements hub sizing reflects configurations you have actually tested

Pattern missing from the UI catalog

Verify the following items:

The GitHub repository has the ui-catalog-enabled topic.
pattern-metadata.yaml exists on the default branch.
The YAML parses correctly (run yq '.' pattern-metadata.yaml locally).
The catalog has been regenerated and the catalog image redeployed after your change.

Metadata sync workflow fails on repo URL

The sync workflow compares repo_url with the GitHub URL of the repository running the workflow. Verify that repo_url uses the form https://github.com/<org>/<repo>;.

Schema validation fails in pattern-ui-catalog

Common causes include the following issues:

Missing required field after normalization (for example, extra_features or requirements.hub)
Invalid tier value (must be maintained, tested, or sandbox)
name contains uppercase letters or underscores
owners is empty after normalization
Undeclared extra fields at the top level

Run make generate-catalog and make schema-validate locally to reproduce errors before publishing. For required fields, see Required fields (catalog format).

Empty requirements section

If requirements is empty, the catalog schema validation fails and the documentation cluster sizing template renders incomplete tables. Define at least requirements.hub with compute and controlPlane entries for one cloud provider.

For sizing field structure, see Cluster sizing fields.