JSON Schemas

Status: Deferred Reference
Priority: Low
Related: Tentacle v4

---

Overview

This document describes the JSON schemas that could be used for programmatic validation of Tentacle ecosystem files. These schemas are not yet implemented but are documented here for future reference.

Planned Schemas

1. tentacle.schema.json

Validates jelly.yaml manifest files.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://jellylabs.ai/schemas/tentacle.schema.json",
  "title": "Tentacle Manifest",
  "type": "object",
  "required": ["name", "version", "type"],
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "description": "Package identifier (lowercase, hyphenated)"
    },
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+$",
      "description": "SemVer version string"
    },
    "type": {
      "type": "string",
      "enum": ["skill", "hook", "command", "plugin", "prompt"],
      "description": "Package type"
    },
    "description": {
      "type": "string",
      "description": "Human-readable description"
    },
    "author": {
      "type": "string",
      "description": "Package author"
    },
    "license": {
      "type": "string",
      "description": "SPDX license identifier"
    },
    "dependencies": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Package dependencies with version constraints"
    },
    "spec_version": {
      "type": "string",
      "pattern": "^\\d+$",
      "description": "Tentacle spec version this package conforms to"
    }
  }
}

2. gnosis.schema.json

Validates gnosis memory files (.claude/gnosis/*.json).

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://jellylabs.ai/schemas/gnosis.schema.json",
  "title": "Gnosis Memory File",
  "type": "object",
  "required": ["project", "updated"],
  "properties": {
    "project": {
      "type": "string",
      "description": "Project identifier"
    },
    "updated": {
      "type": "string",
      "format": "date-time",
      "description": "Last update timestamp"
    },
    "architecture": {
      "type": "object",
      "description": "Architectural knowledge"
    },
    "patterns": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Known patterns in the codebase"
    },
    "decisions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "date": { "type": "string" },
          "decision": { "type": "string" },
          "rationale": { "type": "string" }
        }
      },
      "description": "Recorded decisions"
    },
    "learnings": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Session learnings"
    }
  }
}

3. lock.schema.json

Validates dependency lock files (jelly.lock).

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://jellylabs.ai/schemas/lock.schema.json",
  "title": "Tentacle Lock File",
  "type": "object",
  "required": ["lockfile_version", "packages"],
  "properties": {
    "lockfile_version": {
      "type": "integer",
      "const": 1,
      "description": "Lock file format version"
    },
    "packages": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "required": ["version", "resolved", "integrity"],
        "properties": {
          "version": { "type": "string" },
          "resolved": { "type": "string", "format": "uri" },
          "integrity": { "type": "string" },
          "dependencies": {
            "type": "object",
            "additionalProperties": { "type": "string" }
          }
        }
      },
      "description": "Locked package versions"
    }
  }
}

Implementation Status

Schema	Status	URL
iteration_state.schema.json	Published	/schemas/iteration_state.schema.json
tentacle.schema.json	Published	/schemas/tentacle.schema.json
gnosis.schema.json	Published	/schemas/gnosis.schema.json
lock.schema.json	Published	/schemas/lock.schema.json

Usage

Reference schemas in your files:

# jelly.yaml
$schema: https://jellylabs.ai/schemas/tentacle.schema.json
name: my-skill
version: 1.0.0
type: skill

# iteration_state.yaml
$schema: https://jellylabs.ai/schemas/iteration_state.schema.json
spec_version: v1
iteration_id: ITER-2025-12-28-A

Future Work

1. Add $ref support for shared definitions
2. Integrate with jelly CLI for validation
3. Add editor integration (VS Code, etc.)