harnessprotocol/harness-validate

Validate a Harness Configuration

You are helping the user validate a harness.yaml file against the Harness Protocol v1 JSON Schema.

Workflow Order (MANDATORY)

Follow these steps in order. Do not skip any step.

---

Step 1: Find the file

Check for the harness file in this order:

1. A path provided by the user after /harness-validate (e.g., /harness-validate ~/dotfiles/harness.yaml)
2. ./harness.yaml in the current directory

If no file is found at either location, tell the user:

"No harness.yaml found. Specify a path: /harness-validate path/to/harness.yaml"

Read the file contents.

---

Step 2: Run validation

Install the validation tools if not present and run validation:

python3 -m venv /tmp/hk-validate-venv 2>/dev/null || true
/tmp/hk-validate-venv/bin/pip install jsonschema pyyaml -q 2>/dev/null || \
  (python3 -m venv /tmp/hk-validate-venv && /tmp/hk-validate-venv/bin/pip install jsonschema pyyaml -q)

Then run this validation script:

import json, sys, yaml

try:
    from jsonschema import validate, ValidationError, SchemaError
    from jsonschema.validators import validator_for
except ImportError:
    print("ERROR: jsonschema not installed")
    sys.exit(1)

SCHEMA_URL = "https://raw.githubusercontent.com/harnessprotocol/harness-protocol/spec/v1-foundation/schema/draft/harness.schema.json"
HARNESS_FILE = "harness.yaml"  # replace with actual path

# Fetch the schema
import urllib.request
try:
    with urllib.request.urlopen(SCHEMA_URL, timeout=5) as resp:
        schema = json.loads(resp.read())
except Exception as e:
    print(f"WARN: Could not fetch remote schema ({e}). Falling back to basic checks.")
    schema = None

# Load the harness file
try:
    with open(HARNESS_FILE) as f:
        doc = yaml.safe_load(f)
except yaml.YAMLError as e:
    print(f"FAIL: YAML parse error — {e}")
    sys.exit(1)

if schema is None:
    # Basic offline checks
    errors = []
    if "version" not in doc:
        errors.append("Missing required field: version")
    elif doc["version"] not in ("1", 1):
        errors.append(f"version must be \"1\" (string) or 1 (legacy integer), got: {doc['version']!r}")
    if "metadata" not in doc:
        errors.append("Missing required field: metadata")
    elif "name" not in doc.get("metadata", {}):
        errors.append("metadata.name is required")
    if errors:
        for e in errors:
            print(f"FAIL: {e}")
    else:
        print("PASS (basic checks only — schema fetch failed)")
    sys.exit(0)

# Full schema validation
try:
    validate(instance=doc, schema=schema)
    print("PASS")
except ValidationError as e:
    path = " → ".join(str(p) for p in e.absolute_path) or "(root)"
    print(f"FAIL: {path}: {e.message}")
except SchemaError as e:
    print(f"ERROR: Schema itself is invalid — {e.message}")

Run the script with /tmp/hk-validate-venv/bin/python3 and capture the output.

---

Step 3: Report results

On PASS:

"Your harness.yaml is valid — passes Harness Protocol v1 schema validation."

If the file uses version: 1 (integer, legacy format), add:

"Note: this is in the legacy format (version: 1 integer). Run /harness-export to regenerate in Harness Protocol v1 format (version: \"1\" string)."

On FAIL (validation errors):

Display errors with clear field paths and fix suggestions:

✗ harness.yaml failed validation:

  plugins → 0 → source: 'marketplace' is not a valid property
    Fix: Use source: owner/repo instead of marketplace: key.
    Example: source: harnessprotocol/harness-kit

  env → 0: 'default' is not allowed when sensitive is true
    Fix: Remove the default value — sensitive vars must be set by the user,
    never baked into the harness file.

  (root): version must be "1" (string), got 1 (integer)
    Fix: Change version: 1 to version: "1" (add quotes).

Common errors and their fixes:

| Error | Fix | |-------|-----| | version must be string "1" | Change version: 1 to version: "1" | | source is not a valid property | Replace marketplace: key with source: owner/repo | | default not allowed when sensitive: true | Remove the default value | | metadata.name is required | Add a metadata.name field | | Unknown additional property | Check for typos in field names |

After listing errors:

"Fix these issues and run /harness-validate again to confirm."

On YAML parse error:

"Your harness.yaml has a YAML syntax error: [error details]

Common causes: wrong indentation, missing quotes around special characters (like : in strings), or a tab used instead of spaces."

---

Common Mistakes

| Mistake | Fix | |---------|-----| | Reporting only the first error | Show all errors, not just the first one | | Giving up if schema fetch fails | Fall back to basic checks and tell the user the schema was unavailable | | Suggesting marketplace: as a fix | Always recommend source: owner/repo — that's the v1 format |