​
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.
ComponentRequiredPurposeFormat
Output SchemaYesDefines the structure and fields of the task resultJSON Schema or Text
Input SchemaNoSpecifies expected input parameters and their formatsJSON Schema or Text

​
Task Spec Structure

A Task Spec consists of these key components:
FieldTypeRequiredDescription
outputSchema object or stringYesDescription and structure of the desired output
inputSchema object or stringNoDescription 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

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

RuleTypeDescription
Root type must be objecterrorThe root schema must have "type": "object"
Root must have propertieserrorThe root object must have a properties field
Root cannot use anyOferrorThe root level cannot use anyOf
Standalone null typeerrornull type is only allowed in union types or anyOf
All fields must be requiredwarningAll properties should be listed in the required array
additionalProperties must be falsewarningAll object types should set additionalProperties: false
While all fields must be required in the schema, you can create optional parameters by using a union type with null. For example, "type": ["string", "null"] allows a field to be either a string or null, effectively making it optional while maintaining schema compliance.

​
Size and Complexity Limits

RuleTypeLimitDescription
Nesting deptherror5 levelsMaximum nesting depth of objects and arrays
Total propertieserror100Maximum total number of properties across all levels
Total string lengtherror15,000 charsMaximum total string length for names and values
Enum valueserror500Maximum number of enum values across all properties
Large enum string lengtherror7,500 charsMaximum 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

RuleTypeLimitDescription
Task spec sizeerror10,000 charsMaximum length of the task specification
Total sizeerror15,000 charsMaximum 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
}