JSON Tools Plugin

Advanced JSON analysis and search capabilities for OpenCode. This plugin provides intelligent JSON parsing, schema analysis, and powerful search functionality to help LLMs understand and explore JSON data efficiently.

Features

🔍 Schema Analysis

• Comprehensive JSON structure analysis with type detection
• Nesting depth analysis and data type summaries
• Optional sample value extraction for exploration
• Memory-efficient processing of large JSON files

🔎 Smart Search

• Text-based search with case sensitivity options
• Path-based queries (e.g., user.email, items[*].name)
• Support for array indexing and slicing
• Search across nested structures with configurable depth
• Type-based filtering (string, number, boolean, object, array)

📊 Data Intelligence

• Automatic type detection and classification
• Array structure analysis (uniform vs mixed types)
• Object property counting and key analysis
• File size validation and memory management

Quick Start

Installation

cd pets/json-tools
npm install

Basic Usage

# Analyze a JSON file structure
opencode run "analyze the schema of package.json"

# Search for specific values
opencode run "search for all dependencies in package.json"

# Test the plugin
opencode run "test json tools connection"

Tools

json-tools-test-connection

Test plugin configuration and verify all capabilities are ready.

Usage:

opencode run "test json tools connection"

json-tools-schema-analyze

Analyze JSON structure and return comprehensive schema overview.

Parameters:

• jsonInput (optional): JSON string to analyze
• filePath (optional): Path to JSON file
• includeSampleValues (optional, default: false): Include sample values
• maxDepth (optional, default: 10): Maximum analysis depth
• maxSamples (optional, default: 3): Maximum samples per type

Examples:

# Basic schema analysis
opencode run "analyze the schema of config.json"

# With sample values
opencode run "analyze the schema of package.json with sample values"

# Custom depth limit
opencode run "analyze schema of large-data.json with max depth 5"

json-tools-search

Search for values, patterns, or paths in JSON data.

Parameters:

• query: Search query or path expression
• jsonInput (optional): JSON string to search
• filePath (optional): Path to JSON file
• caseSensitive (optional, default: false): Case sensitive search
• exactMatch (optional, default: false): Exact vs contains matching
• maxDepth (optional, default: 10): Maximum search depth
• valueTypes (optional, default: ["string", "number", "boolean"]): Types to search
• maxResults (optional, default: 50): Maximum results to return
• includeContext (optional, default: false): Include surrounding context

Examples:

# Text search
opencode run "search for 'test' in config.json"

# Path-based query
opencode run "search for dependencies in package.json"

# Array wildcard search
opencode run "search for users[*].email in data.json"

# Case sensitive exact match
opencode run "search for 'Production' in config.json case sensitive exact"

# Search specific types
opencode run "search for numbers in metrics.json"

Search Query Patterns

Text Search

search for 'error' in logs.json
search for 'version' in package.json

Path Navigation

search for user.name in profile.json
search for config.database.host in settings.json

Array Operations

search for items[*].name in catalog.json
search for users[0].email in data.json
search for products[1:5].price in inventory.json

Advanced Options

search for 'API_KEY' in config.json case sensitive exact
search for 'test' in logs.json max depth 20
search for strings in data.json value types string

Configuration

Environment Variables

Optional environment variables for customization:

# Maximum file size for JSON processing (default: 50MB)
JSON_TOOLS_MAX_FILE_SIZE=100

# Maximum search depth for nested structures (default: 10)
JSON_TOOLS_SEARCH_DEPTH=15

Performance Considerations

• Large JSON files are automatically validated against size limits
• Use includeSampleValues=false for memory-efficient analysis
• Limit search depth with maxDepth parameter for deep structures
• Use type filtering to focus on relevant data types

Response Format

All tools return structured JSON responses:

Schema Analysis Response

{
  "success": true,
  "schema": {
    "path": "root",
    "type": "object",
    "depth": 3,
    "keyCount": 5,
    "properties": { /* detailed schema */ }
  },
  "summary": {
    "totalDepth": 3,
    "arrayCount": 2,
    "objectCount": 5,
    "stringCount": 8,
    "numberCount": 3,
    "booleanCount": 1
  },
  "samples": { /* optional sample values */ }
}

Search Response

{
  "success": true,
  "query": "dependencies",
  "totalMatches": 15,
  "returnedMatches": 15,
  "hasMore": false,
  "searchOptions": {
    "caseSensitive": false,
    "exactMatch": false,
    "maxDepth": 10
  },
  "results": [
    {
      "value": "react",
      "path": "dependencies.react",
      "type": "string",
      "depth": 2
    }
  ]
}

Use Cases

Configuration Analysis

# Understand complex configuration files
opencode run "analyze schema of webpack.config.json"

# Find specific configuration values
opencode run "search for 'port' in server-config.json"

API Response Exploration

# Analyze API response structure
opencode run "analyze schema of api-response.json with sample values"

# Extract specific data
opencode run "search for data[*].id in api-response.json"

Data Discovery

# Explore datasets
opencode run "analyze schema of large-dataset.json"

# Find patterns
opencode run "search for 'error' in logs.json value types string"

Error Handling

The plugin provides comprehensive error handling:

{
  "success": false,
  "error": "File size (120.5MB) exceeds maximum allowed size (50MB)",
  "details": {
    "input": "file: large-data.json"
  }
}

Common errors:

• Invalid JSON syntax
• File size exceeded
• File not found
• Invalid search parameters

Examples

Real-World Scenarios

1. Package.json Analysis

# Understand project dependencies
opencode run "analyze schema of package.json"

# Find all dependencies
opencode run "search for dependencies in package.json"

# Check scripts
opencode run "search for scripts in package.json"

2. Config File Debugging

# Find database configuration
opencode run "search for 'database' in config.json"

# Check for API keys
opencode run "search for 'api' in config.json case sensitive"

3. Data Processing

# Extract user emails
opencode run "search for users[*].email in users.json"

# Find status values
opencode run "search for status in data.json"

Contributing

This plugin is part of the OpenPets ecosystem. For issues, feature requests, or contributions:

1. Check existing issues in the repository
2. Follow the OpenPets development patterns
3. Test thoroughly with various JSON structures
4. Update documentation for new features

License

Part of the OpenPets project. See main project license for details.