Task Spec

Definition

A Task Specification (Task Spec) is a declarative template that defines the structure and requirements for the outputs of a web research operation. While optional in each Task Run, Task Specs provide significant advantages when you need precise control over your research data.

Task Specs ensure consistent results by enforcing a specific output structure across multiple runs. They validate schema against expected formats and create reusable templates for common research patterns. By defining the expected outputs clearly, they also serve as self-documentation for your tasks, making them easier to understand and maintain.

Component	Required	Purpose	Format
Output Schema	Yes	Defines the structure and fields of the task result	JSON Schema or Text
Input Schema	No	Specifies expected input parameters and their formats	JSON Schema or Text

Task Spec Structure

A Task Spec consists of these key components:

Field	Type	Required	Description
`output`	Schema object or string	Yes	Description and structure of the desired output
`input`	Schema object or string	No	Description and structure of input parameters

When providing a bare string for input or output, it’s equivalent to a text schema with that string as the description.

Schema Types

Task Spec supports two schema formats:

When using the Python SDK, the Parallel Task API also supports Pydantic objects in Task Spec

{
  "json_schema": {
    "type": "object",
    "properties": {
      "population": {
        "type": "string",
        "description": "Current population with year of estimate"
      },
      "area": {
        "type": "string",
        "description": "Total area in square kilometers and square miles"
      }
    },
    "required": ["population", "area"]
  },
  "type": "json"
}

{
  "json_schema": {
    "type": "object",
    "properties": {
      "population": {
        "type": "string",
        "description": "Current population with year of estimate"
      },
      "area": {
        "type": "string",
        "description": "Total area in square kilometers and square miles"
      }
    },
    "required": ["population", "area"]
  },
  "type": "json"
}

{
  "description": "Summary of the country's economic indicators for 2023",
  "type": "text"
}

JSON Schema

The JSON schema format provides structured outputs with defined field types. It enables type validation to ensure values match expected types like strings, numbers, and arrays. You can specify required fields that must be present in the response and create nested structures for hierarchical data organization. This format is ideal when you need precise control over the structure of your research results.

Text Schema

The text schema format is simpler, accepting or returning plain text. This format works well when you need a straightforward text answer, when the structure is less important than the content itself, or when you want to avoid the complexity of JSON schemas. Text schemas are perfect for questions that require narrative responses rather than structured data.

Field Descriptions

The field descriptins in output schema are critically important to how your Task performs. These descriptions serve as instructions for the Processor on how to interpret fields. More specific descriptions lead to more accurate results, so aim to make them clear, concise, and unambiguous.

Example: Poor vs. Good Descriptions

{
  "properties": {
    "gdp": {
      "type": "string",
      "description": "GDP"
    }
  }
}

Output Schema Validation Rules

The Task API enforces several restrictions on output schemas to ensure compatibility and performance:

Schema Structure Rules

Rule	Type	Description
Root type must be object	error	The root schema must have `"type": "object"`
Root must have properties	error	The root object must have a `properties` field
Root cannot use anyOf	error	The root level cannot use `anyOf`
Standalone null type	error	`null` type is only allowed in union types or anyOf
All fields must be required	warning	All properties should be listed in the `required` array
additionalProperties must be false	warning	All object types should set `additionalProperties: false`

Size and Complexity Limits

Rule	Type	Limit	Description
Nesting depth	error	5 levels	Maximum nesting depth of objects and arrays
Total properties	error	100	Maximum total number of properties across all levels
Total string length	error	15,000 chars	Maximum total string length for names and values
Enum values	error	500	Maximum number of enum values across all properties
Large enum string length	error	7,500 chars	Maximum string length for enums with >250 values

Unsupported Keywords

The following JSON Schema keywords are not supported in output schemas:

contains, format, maxContains, maxItems, maxLength, maxProperties, maximum, minContains, minItems, minLength, minimum, minProperties, multipleOf, pattern, patternProperties, propertyNames, uniqueItems, unevaluatedItems, unevaluatedProperties

Task Specification Size Limits

Rule	Type	Limit	Description
Task spec size	error	10,000 chars	Maximum length of the task specification
Total size	error	15,000 chars	Maximum combined length of task specification and input data

Examples

Valid Output Schema

Here’s an example of a properly structured output schema for company research:

{
  "type": "object",
  "properties": {
    "company_name": {
      "type": "string",
      "description": "The name of the company"
    },
    "founded_year": {
      "type": "integer",
      "description": "The year the company was founded"
    },
    "headquarters": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "The city where the company is headquartered"
        },
        "country": {
          "type": "string",
          "description": "The country where the company is headquartered"
        }
      },
      "required": ["city", "country"],
      "additionalProperties": false
    }
  },
  "required": ["company_name", "founded_year", "headquarters"],
  "additionalProperties": false
}

This schema follows all requirements: it has an object root type with properties, all fields are required, and additionalProperties is set to false.

Common Errors to Avoid

Here are examples of common schema errors and how to fix them:

{
  "type": "array",  // Error: Root type must be "object"
  "items": {
    "type": "object",
    "properties": {
      "name": { "type": "string" }
    }
  }
}

Fix: Change the root type to “object” and move array properties to a field:

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" }
        },
        "required": ["name"]
      }
    }
  },
  "required": ["items"],
  "additionalProperties": false
}

{
  "type": "array",  // Error: Root type must be "object"
  "items": {
    "type": "object",
    "properties": {
      "name": { "type": "string" }
    }
  }
}

Fix: Change the root type to “object” and move array properties to a field:

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" }
        },
        "required": ["name"]
      }
    }
  },
  "required": ["items"],
  "additionalProperties": false
}

{
  "type": "object",
  "anyOf": [  // Error: Root level cannot use anyOf
    {
      "properties": {
        "field1": { "type": "string" }
      }
    },
    {
      "properties": {
        "field2": { "type": "string" }
      }
    }
  ]
}

Fix: Combine the properties into a single object:

{
  "type": "object",
  "properties": {
    "field1": { "type": "string" },
    "field2": { "type": "string" }
  },
  "required": ["field1", "field2"],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "field1": { "type": "string" },
    "field2": { "type": "string" }
  },
  "required": ["field1"]  // Warning: All fields should be required
}

Fix: Add all fields to the required array:

{
  "type": "object",
  "properties": {
    "field1": { "type": "string" },
    "field2": { "type": "string" }
  },
  "required": ["field1", "field2"],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "field1": { "type": "string" },
    "field2": { "type": "string" }
  },
  "required": ["field1", "field2"],
  "additionalProperties": true  // Warning: should be false
}

Fix: Set additionalProperties to false:

{
  "type": "object",
  "properties": {
    "field1": { "type": "string" },
    "field2": { "type": "string" }
  },
  "required": ["field1", "field2"],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "field1": {
      "type": "string",
      "minLength": 5  // Error: Unsupported keyword
    }
  },
  "required": ["field1"],
  "additionalProperties": false
}

Fix: Remove unsupported keywords and use descriptions instead:

{
  "type": "object",
  "properties": {
    "field1": {
      "type": "string",
      "description": "A string with at least 5 characters"
    }
  },
  "required": ["field1"],
  "additionalProperties": false
}

Introduction

Core Concepts

Resources

Definition

Task Spec Structure

Schema Types

JSON Schema

Text Schema

Field Descriptions

Example: Poor vs. Good Descriptions

Output Schema Validation Rules

Schema Structure Rules

Size and Complexity Limits

Unsupported Keywords

Task Specification Size Limits

Examples

Valid Output Schema

Common Errors to Avoid

Introduction

Core Concepts

Resources

​Definition

​Task Spec Structure

​Schema Types

​JSON Schema

​Text Schema

​Field Descriptions

​Example: Poor vs. Good Descriptions

​Output Schema Validation Rules

​Schema Structure Rules

​Size and Complexity Limits

​Unsupported Keywords

​Task Specification Size Limits

​Examples

​Valid Output Schema

​Common Errors to Avoid

Definition

Task Spec Structure

Schema Types

JSON Schema

Text Schema

Field Descriptions

Example: Poor vs. Good Descriptions

Output Schema Validation Rules

Schema Structure Rules

Size and Complexity Limits

Unsupported Keywords

Task Specification Size Limits

Examples

Valid Output Schema

Common Errors to Avoid