validate-requirements

name	validate-requirements
license	Apache-2.0 AND CC-BY-4.0
description	Author and validate USD Validation requirements: Markdown specs, codegen, rule mapping, --requirement CLI. Do NOT use for basic plugins.
metadata	{"version":"1.19.1","author":"NVIDIA <[e-mail]>","tags":["usd-validation","requirements","codegen"]}
compatibility	Requires Python 3.10-3.14, uv or pip, network access to Python package indexes, and Linux/macOS shell or Windows PowerShell command syntax.

Validate Requirements

Purpose

usd-validation-nvidia extensions are Python plugin packages discovered through entry points. This skill shows the smallest useful plugin that registers one rule backed by one requirement. The requirement is authored as Markdown and generated with usd-profiles-nvidia; the rule registration, execution, and CLI filtering stay in usd-validation-nvidia.

Prerequisites

• Python 3.10-3.14.
• uv or pip with package-index access.

Project Structure

my-usd-validation-plugin/
  pyproject.toml
  main.py
  specs/
    capabilities/
      capability-example.md
      requirements/
        default-prim.md

After uv init, create main.py, specs/, and the Markdown spec files manually or copy them from the example.

Verify Python Version

This skill requires Python 3.10-3.14. Before setup, run uv run --python 3.11 python --version or py -3.11 --version on Windows; use 3.10, 3.12, 3.13, or 3.14 instead if that is the supported interpreter. If no supported interpreter is available, stop with: "This skill requires Python 3.10-3.14. Install a supported interpreter, then rerun." For uv workflows, install one with uv python install 3.11.

Setup with uv (Recommended)

Start from a clean parent directory outside this workspace where my-usd-validation-plugin does not already exist. If that folder already exists, choose a different folder name or move the existing folder aside before continuing.

mkdir -p my-usd-validation-plugin && cd my-usd-validation-plugin
uv init --no-workspace --python 3.11
uv add "usd-validation-nvidia[usd]"

Declare the plugin entry point in pyproject.toml:

[project.entry-points."usd_validation_nvidia"]
my_plugin = "main:Plugin"

Setup with pip

pip install "usd-validation-nvidia[usd]"
pip install -e .

Examples

Minimal Requirement

Source: validation/examples/python/requirement/pyproject.toml

Source: validation/examples/python/requirement/specs/capabilities/requirements/default-prim.md

Followed by: validation/examples/python/requirement/specs/capabilities/capability-example.md

Generate

From the repository root:

uv run \
  --no-project \
  --with ./profiles \
  python -m usd_profiles_nvidia.codegen \
    --docs-root validation/examples/python/requirement/specs \
    --destination-dir validation/examples/python/requirement \
    --package-name example_requirements \
    --reverse-domain com.nvidia.usd

On Windows:

uv run `
  --no-project `
  --with ./profiles `
  python -m usd_profiles_nvidia.codegen `
    --docs-root validation/examples/python/requirement/specs `
    --destination-dir validation/examples/python/requirement `
    --package-name example_requirements `
    --reverse-domain com.nvidia.usd

The example package force-includes example_requirements, so skipping this step fails during wheel build.

Minimal main.py

Source: validation/examples/python/requirement/main.py snippet custom-requirement

Followed by: validation/examples/python/requirement/main.py snippet custom-rule

Followed by: validation/examples/python/requirement/main.py snippet plugin-entry-point

Asset: validation/examples/assets/asset.usda

Use requirement=... when reporting the issue so --requirement filtering can connect the rule failure back to the generated requirement.

Run

From the repository root:

uv run \
  --no-project \
  --with ./profiles \
  python -m usd_profiles_nvidia.codegen \
    --docs-root specs \
    --destination-dir validation/src \
    --package-name usd_validation_nvidia.capabilities \
    --reverse-domain com.nvidia.usd
uv run \
  --with ./validation \
  --with validation/examples/python/requirement \
  nvidia_usd_validate --requirement EXAMPLE.001 validation/examples/assets/asset.usda

To see the requirement-mapped failure:

uv run \
  --with ./validation \
  --with validation/examples/python/requirement \
  nvidia_usd_validate --requirement EXAMPLE.001 validation/examples/assets/asset-missing-default-prim.usda

On Windows:

uv run `
  --no-project `
  --with ./profiles `
  python -m usd_profiles_nvidia.codegen `
    --docs-root specs `
    --destination-dir validation/src `
    --package-name usd_validation_nvidia.capabilities `
    --reverse-domain com.nvidia.usd
uv run `
  --with ./validation `
  --with validation/examples/python/requirement `
  nvidia_usd_validate --requirement EXAMPLE.001 validation/examples/assets/asset.usda

To see the requirement-mapped failure on Windows:

uv run `
  --with ./validation `
  --with validation/examples/python/requirement `
  nvidia_usd_validate --requirement EXAMPLE.001 validation/examples/assets/asset-missing-default-prim.usda

Note: replace --with ./validation with --with usd-validation-nvidia to use the public build.

Key Types / Functions

• register_rule("Example"): registers the rule in the Example category; the string argument is the rule category shown by the CLI.
• register_requirements(...): maps a rule class to one or more generated requirements so --requirement filtering and reports can connect failures back to requirement IDs.
• _AddFailedCheck(requirement=...): reports a validation failure associated with a generated requirement.

Key Dependencies

Package	Purpose
usd-validation-nvidia[usd]	Engine, CLI, plugin discovery, and usd-core runtime dependency
usd-profiles-nvidia	Codegen package for generated requirements

Limitations

• Covers requirement-backed plugins only; use project-setup-python for basic custom rule plugins.
• Does not author full production capability models beyond the minimal example.

Common Pitfalls

• Install the plugin package into the same environment as usd-validation-nvidia.
• Use the usd_validation_nvidia entry-point group for new plugins.
• In a fresh source checkout, generate validation/src/usd_validation_nvidia/capabilities with uv run --no-project --with ./profiles python -m usd_profiles_nvidia.codegen ... before commands that install the local repo with --with ./validation.
• Generate example_requirements before installing or running the example plugin.
• Requirements must live under a capability; an otherwise minimal capability Markdown file is enough for this example.
• Register requirements and rules in on_startup(), and unregister them in on_shutdown().
• Pass the same requirement object to register_requirements(...) and _AddFailedCheck(requirement=...).
• Confirm the requirement appears in nvidia_usd_validate --help before debugging rule behavior.

Troubleshooting

• If installing or running the example fails because example_requirements is missing, run requirement codegen before building or installing the example plugin.
• If --requirement EXAMPLE.001 does not select the custom rule, confirm the requirement package is generated, installed with the plugin, and registered from on_startup().