Object Extractor Tool

Overview

Object Extractor Tool is a Dify plugin that provides powerful JSONPath-based extraction capabilities for objects, arrays, and JSON strings. It automatically converts extracted values to appropriate types and provides type-safe outputs across multiple data types.

Features

• JSONPath Support: Full JSONPath syntax support for complex data extraction
• Automatic Type Conversion: Extracted values are automatically converted to the appropriate type
• Multiple Data Types: Supports boolean, number, string, and array types (including array of objects)
• Three Extraction Tools:
  • object_extract: Extract values from objects
  • array_extract: Extract values from arrays
  • string_extract: Parse and extract from JSON strings
• Default Values: Returns sensible defaults when values are not found
• Nested Path Support: Handle deeply nested objects and arrays

Tools

1. Extract Value from Object

Extract values from objects using JSONPath expressions.

Tool Name: object_extract

Parameters:

• target_object (required): The target object to extract from (object, array, or JSON string)
• path (required): JSONPath expression to extract the value

Example Usage:

// Input object
{
  "user": {
    "id": 123,
    "name": "John Doe",
    "email": "john@example.com",
    "active": true,
    "tags": ["developer", "admin"]
  }
}

// Extraction examples:
Path: "$.user.id"        → output_number: 123
Path: "$.user.name"      → output_string: "John Doe"
Path: "$.user.active"    → output_boolean: true
Path: "$.user.tags"      → output_array_string: ["developer", "admin"]

Nested Object Example:

// Input object
{
  "data": {
    "items": [
      {"id": 1, "name": "Item 1"},
      {"id": 2, "name": "Item 2"}
    ]
  }
}

// Extraction:
Path: "$.data.items[0].name"  → output_string: "Item 1"
Path: "$.data.items[0].id"    → output_number: 1

2. Extract Value from Array

Extract values from arrays using JSONPath expressions. The array can contain any type of elements (objects, strings, numbers, booleans, etc.).

Tool Name: array_extract

Parameters:

• array (required): The target array to extract from (array or JSON string)
• path (required): JSONPath expression to extract the value

Example Usage:

// Simple array
[
  {"id": 1, "name": "Alice"},
  {"id": 2, "name": "Bob"},
  {"id": 3, "name": "Charlie"}
]

// Extraction examples:
Path: "$[0].name"     → output_string: "Alice"
Path: "$[0].id"       → output_number: 1
Path: "$[1].name"     → output_string: "Bob"

Array of Primitives:

// Array of numbers
[10, 20, 30, 40]

Path: "$[0]"    → output_number: 10

Array of Nested Objects:

[
  {
    "user": {"name": "Alice", "scores": [95, 87, 92]},
    "active": true
  }
]

Path: "$[0].user.name"       → output_string: "Alice"
Path: "$[0].user.scores"     → output_array_number: [95, 87, 92]
Path: "$[0].active"          → output_boolean: true

3. Extract from String

Parse a JSON string and extract values using JSONPath. This is particularly useful when working with HTTP responses or other string-based JSON data.

Tool Name: string_extract

Parameters:

• json_string (required): The JSON string to parse (can be escaped)
• path (required): JSONPath expression to extract the value

Example Usage:

// JSON string input (can be from HTTP response, etc.)
"{\"id\":\"123\",\"name\":\"John Doe\",\"meta\":{\"company_id\":\"456\"}}"

// Extraction examples:
Path: "$.id"              → output_string: "123"
Path: "$.name"            → output_string: "John Doe"
Path: "$.meta.company_id" → output_string: "456"
Path: "$"                 → Returns entire parsed object

Use Case: HTTP Response Processing

When using Dify's HTTP Request node, responses often come as strings. Use string_extract to parse and extract specific fields:

// HTTP Response body (as string)
"{\"status\":\"success\",\"data\":{\"userId\":789,\"email\":\"user@example.com\"}}"

// Extract user ID
Path: "$.data.userId"   → output_number: 789

// Extract email
Path: "$.data.email"    → output_string: "user@example.com"

Output Schema

All three tools share the same output schema with automatic type conversion:

Output Field	Type	Description	Default Value
output_boolean	boolean	Extracted boolean value	-1 (if not set)
output_number	number	Extracted number value	-1 (if not set)
output_string	string	Extracted string value	"" (empty string)
output_array_boolean	array[boolean]	Extracted boolean array	[] (empty array)
output_array_number	array[number]	Extracted number array	[] (empty array)
output_array_string	array[string]	Extracted string array	[] (empty array)
output_array_object	array[object]	Extracted object array	[] (empty array)
output_any	string	String representation of any extracted value	"" (empty string)

How to Use Outputs:

• The tool automatically places the extracted value in the appropriate typed output field
• Use the specific type field (e.g., output_number) when you know the expected type
• Use output_any for generic string representation of any value
• If a value is not found, each field returns its respective default value

Common Use Cases

1. API Response Processing

Extract specific fields from HTTP API responses:

HTTP Request → string_extract
  Input: Response body as JSON string
  Path: "$.data.items"
  Output: output_array_object (list of items)

2. Data Transformation Pipelines

Transform nested data structures by extracting specific values:

Complex Object → object_extract
  Input: {users: [{id: 1, profile: {email: "a@b.com"}}]}
  Path: "$.users[0].profile.email"
  Output: output_string ("a@b.com")

3. Array Processing

Process array elements in workflows:

Array of Users → array_extract
  Input: [{id: 1, name: "Alice"}, {id: 2, name: "Bob"}]
  Path: "$[0].name"
  Output: output_string ("Alice")

4. Configuration Parsing

Extract configuration values from JSON strings:

Config String → string_extract
  Input: "{\"api_key\":\"abc123\",\"timeout\":30}"
  Path: "$.timeout"
  Output: output_number (30)

JSONPath Syntax Reference

Common JSONPath patterns supported:

Pattern	Description	Example
$	Root element	$
.property	Property access	$.user.name
['property']	Bracket notation	$['user']['name']
[index]	Array index	$.items[0]
[start:end]	Array slice	$.items[0:2]
[*]	Wildcard (all elements)	$.users[*].name
..property	Recursive descent	$..email

Error Handling

• Invalid JSONPath: Returns default values for all output types
• Path Not Found: Returns default values based on the expected type
• Invalid JSON String (string_extract only): Returns default values
• Type Mismatch: Attempts automatic conversion; returns default on failure

Requirements

• Python: 3.12 or higher
• Dify Version: Compatible with Dify plugin system
• Dependencies: jsonpath-ng (automatically installed)

License

See PRIVACY.md for privacy and licensing information.

Contributing

For bug reports or feature requests, please contact the author: cazziwork

Changelog

Version 0.2.0

• Added string_extract tool for JSON string parsing
• Enhanced type conversion and default value handling
• Improved JSONPath support for complex nested structures