Ukiryu Schemas

Schemas for validating Ukiryu tool profile YAML files.

Purpose

This repository contains the YAML Schema used to validate YAML tool profiles for the Ukiryu platform-adaptive command execution framework.

Schema files

tool.schema.yaml

Validation schema for tool profiles including:

• Tool metadata (name, version, interface, implementations)

• Implementation routing (version matching with equals/after/before)

• Version detection rules

• Platform-specific search paths

• Profile configurations (platforms, shells, versions)

• Command definitions (arguments, options, flags)

• Option styles and formatting rules

interface.schema.yaml

Validation schema for interface definitions including:

• Interface metadata (name, version, display_name, description)

• Command definitions defining the interface contract

• Parameter and option specifications

• Argument and flag definitions

Interface schemas define the abstract contract that multiple tools can implement. For example:

• ping interface - Implemented by ping_bsd, ping_gnu, ping_windows

• grep interface - Implemented by grep_gnu, grep_busybox

• tar interface - Implemented by tar_gnu, tar_busybox

Example interface schema structure:

name: ping
version: "1.0"
display_name: Ping
description: Network ping tool interface

commands:
  - name: ping
    description: Send ICMP echo requests
    arguments:
      - name: host
        type: string
        required: true
    options:
      - name: count
        type: integer
    flags:
      - name: verbose

Schema validation

Validate a tool profile against the schema using the Ukiryu CLI:

# Install ukiryu
gem install ukiryu

# Validate a specific profile
ukiryu validate --definition tools/imagemagick/7.1.yaml

# Validate with schema from schemas repository
ukiryu validate --definition tools/imagemagick/7.1.yaml \
  --schema ../schemas/tool.schema.yaml

# Validate all profiles in the register
ukiryu validate all

Programmatic validation:

require 'ukiryu'

result = Ukiryu::Definition::DefinitionValidator.validate_file('path/to/profile.yaml')

if result.valid?
  puts "✓ Valid"
else
  puts "✗ Invalid:"
  result.errors.each { |e| puts "  - #{e}" }
end

Error namespace structure

All Ukiryu errors are organized in the Ukiryu::Errors namespace:

• Ukiryu::Errors::Error - Base error class

• Ukiryu::Errors::DefinitionError - Base for definition-related errors

• Ukiryu::Errors::DefinitionNotFoundError - Definition file not found

• Ukiryu::Errors::DefinitionLoadError - Failed to load/parse definition

• Ukiryu::Errors::DefinitionValidationError - Definition validation failed

• Ukiryu::Errors::ToolNotFoundError - Tool not found in register

• Ukiryu::Errors::ProfileNotFoundError - No compatible profile found

• Ukiryu::Errors::ExecutionError - Command execution failed

• Ukiryu::Errors::TimeoutError - Command timed out

• Ukiryu::Errors::ValidationError - Type validation failed

• Ukiryu::Errors::UnknownShellError - Unknown shell type

• Ukiryu::Errors::UnsupportedPlatformError - Unsupported platform

Example error handling:

begin
  tool = Ukiryu::Tool.load('tool.yaml')
  result = tool.execute(:convert, params)
rescue Ukiryu::Errors::DefinitionNotFoundError => e
  puts "Definition file not found"
rescue Ukiryu::Errors::ExecutionError => e
  puts "Command failed: #{e.message}"
rescue Ukiryu::Errors::TimeoutError => e
  puts "Command timed out"
end

Usage in Ukiryu

The schema is included as a git submodule in the Ukiryu gem and used by Ukiryu::SchemaValidator.

require 'ukiryu'

Ukiryu::SchemaValidator.validate_profile('path/to/profile.yaml')

Structure

Tool definition schema

tool.schema.yaml
├── Tool metadata
│   ├── ukiryu_schema (required) - Schema version (e.g., "1.0")
│   ├── name (required) - Tool identifier
│   ├── display_name - Human-readable name
│   ├── version - Tool version or "generic"
│   └── interface - Interface contract (for implementations)
├── Implementation index (for index.yaml files)
│   ├── implementations - Array of implementation definitions
│   │   ├── name - Implementation identifier
│   │   ├── display_name - Human-readable name
│   │   ├── detection - Version detection pattern
│   │   ├── version_scheme - semantic or calver
│   │   ├── versions - Version routing rules
│   │   │   ├── equals - Exact version match
│   │   │   ├── after - Semantic version range (>)
│   │   │   ├── before - Semantic version range (<)
│   │   │   └── file - Actual YAML file to load
│   │   └── default - Default file when no version matches
│   └── ...
├── Version detection
│   ├── command - Detection command
│   ├── pattern - Version regex
│   └── modern_threshold - Minimum modern version
├── Search paths
│   ├── macos - macOS executable locations
│   ├── linux - Linux executable locations
│   └── windows - Windows executable locations
├── Profiles
│   ├── platforms - Supported platforms
│   ├── shells - Supported shells
│   ├── version - Profile version
│   ├── option_style - Option format style
│   └── commands - Command definitions
│       ├── name - Command name
│       ├── description - Command description
│       ├── subcommand - Executable subcommand
│       ├── arguments - Argument definitions
│       ├── options - Option definitions
│       └── flags - Flag definitions

Version routing rules

The versions array in an implementation index defines how detected versions map to actual YAML files:

• Exact match: equals: "1.35" matches only version 1.35

• Greater than: after: "1.35" matches any version > 1.35 (semantic)

• Less than: before: "2.0" matches any version < 2.0 (semantic)

Version specs are evaluated in order, with the first match winning. The file field must point to an actual YAML file that exists in the implementation directory.

Example:

versions:
  # Match exactly version 1.35
  - equals: "1.35"
    file: "1.35.yaml"

  # Match versions after 1.35 (fallback to latest available)
  - after: "1.35"
    file: "1.35.yaml"

  # Default when no version matches
  default: "1.35.yaml"

Contributing

When adding new profile features:

1. Update the schema

2. Add validation tests

3. Update documentation

4. Tag a new version

License

The content is available as open source under the terms of the Ribose BSD 2-Clause License.

Copyright

Copyright Ribose.