ShydaSHYDAPLATFORM
Vega SDK — Manifest & Validation API

Manifest and Validation API

Definition models, the package validator, and version compatibility helpers. Manifest symbols are imported from vega_capability_sdk.manifests.

Import

python
from vega_capability_sdk.manifests import (
    MANIFEST_FILENAME,
    SUPPORTED_API_VERSIONS,
    ActionDefinition,
    ActionExecutionProperties,
    CapabilityDefinition,
    CapabilityManifestError,
    CapabilityMetadata,
    CapabilityPackageValidator,
    CompatibilityDeclaration,
    DependencyDeclaration,
    IdempotencyMode,
    OperatingSystemCompatibility,
    ProviderDescriptor,
    PythonDependency,
    ResourceDeclaration,
    ResourceMode,
    RestartRecoveryPolicy,
    is_sdk_compatible,
    require_sdk_compatible,
    validate_capability_package,
    versions_compatible,
)

Constants and enums

TermMeaning
MANIFEST_FILENAME"capability.yaml"
SUPPORTED_API_VERSIONSFrozen set containing "vcp.shyda.ai/v1alpha1"
ResourceModeexclusive, shared
IdempotencyModeidempotent, non_idempotent, conditional
RestartRecoveryPolicyrestart, resume, re_evaluate, manual_confirmation, not_recoverable

Definition models

All definition models are frozen, slot-based dataclasses; JSON mapping fields are recursively immutable.

TermMeaning
OperatingSystemCompatibilityname, versions
CompatibilityDeclarationmanufacturers, models, model_variants, robot_types, architectures, operating_systems, ros_distributions, compute_platforms, required_features
PythonDependencypackage, optional version
DependencyDeclarationpython tuple + frozen raw mapping
ResourceDeclarationid, mode (default exclusive)
ProviderDescriptorprovider_id, runtime, entrypoint
CapabilityMetadatacapability_id, name, version, optional description/publisher/license/labels
ActionExecutionPropertiesdefault_timeout_seconds, cancellation, pause, resume, progress, idempotency, restart_recovery
ActionDefinitionaction_id, version, input/output/progress schemas, resources, execution, self_description
CapabilityDefinitionapi_version, metadata, sdk_version_range, provider, actions, compatibility, dependencies, resources, configuration_defaults, secrets, package_path, package_digest

Validation

python
class CapabilityManifestError(ValueError):
    def __init__(self, message: str, *, details: dict[str, Any] | None = None) -> None: ...


class CapabilityPackageValidator:
    def validate_package(self, package_path: Path) -> CapabilityDefinition: ...
    def validate_payload(
        self,
        schema: dict[str, Any] | Any,
        payload: dict[str, Any] | Any,
        *,
        context: str,
    ) -> None: ...

validate_package reads capability.yaml, validates it and referenced schema files, and returns a CapabilityDefinition. validate_payloadvalidates a payload using JSON Schema Draft 2020-12. Both raiseCapabilityManifestError on invalid input.

Package validation rules

Root and SDK compatibility

  • capability.yaml must exist at the package root and contain a YAML object.
  • apiVersion must be one of SUPPORTED_API_VERSIONS; kind must equal Capability.
  • metadata, vega, provider, and actions must have the required shape.
  • vega.sdkVersion is required and must include the installed SDK version per PEP 440.

Metadata

  • metadata.id must match ^[a-z0-9][a-z0-9._-]*$.
  • metadata.version must match three numeric components with an optional +/- suffix.
  • metadata.name is required; metadata.labels, when supplied, must be an object.

Provider

  • provider.id, provider.runtime, and provider.entrypoint are required.
  • The only accepted runtime is python; the entrypoint must use the module:Class form.
  • Validation does not import the module or verify that the class exists.

Actions and schemas

  • At least one Action is required; IDs match ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$ and must be unique.
  • Input and output schema paths are required; referenced paths must remain inside the resolved package root.
  • Schema files must be valid JSON Schema Draft 2020-12 documents.
  • progress=true requires progressSchema; resume=true requires pause=true.
  • Every Action requires an object-valued contract validated as an ActionSelfDescription.

Resources and recovery

  • Each resource entry requires id; repeated IDs must not conflict on mode.
  • Every resource referenced by an Action must be declared.
  • restartRecovery=resume requires execution.resume=true.

validate_capability_package

python
def validate_capability_package(path: str | Path) -> CapabilityDefinition: ...


definition = validate_capability_package("./my-capability")
action = definition.action_by_id("example.echo.run")

Version compatibility

TermMeaning
is_sdk_compatible(version_range, *, current_sdk_version=None)PEP 440 specifier check; returns False for invalid input.
require_sdk_compatible(version_range, *, current_sdk_version=None, capability_id=None)Raises ValueError when compatibility is not satisfied.
versions_compatible(requested, available)Compares parsed PEP 440 versions; falls back to string comparison on parse failure.