JsonParser

Overview

The JsonParser block parses JSON strings into JavaScript objects so you can access their properties in assertions and subsequent blocks.

{
  "block": "JsonParser",
  "input": "${response.body}",
  "output": {
    "parsed": "data"
  }
}

Input Parameters

Required

Parameter	Type	Description
`body`	string	JSON string to parse

Output Fields

On Success

Field	Type	Description
`parsed`	object/array	The parsed JSON data

On Failure

Field	Type	Description
`error`	string	Error message describing parse failure
`raw`	string	Original unparsed body

Examples

Basic Usage

{
  "pipeline": [
    {
      "block": "HttpRequest",
      "input": {
        "url": "https://api.example.com/users/1",
        "method": "GET"
      },
      "output": "response"
    },
    {
      "block": "JsonParser",
      "input": "${response.body}",
      "output": {
        "parsed": "user"
      }
    }
  ],
  "assertions": {
    "user.id": 1,
    "user.name": { "matches": ".+" }
  }
}

Flow:

HttpRequest returns: { body: '{"id": 1, "name": "John"}' }
JsonParser parses to: { parsed: { id: 1, name: "John" } }
Stored in DataBus as: user = { id: 1, name: "John" }
Assertions can access user.id and user.name

Using String Input Format

{
  "block": "JsonParser",
  "input": "${response.body}",
  "output": "parsed"
}

This automatically wraps the string as { body: value }: Access with: ${parsed.parsed.id}

Using Object Format (Recommended)

{
  "block": "JsonParser",
  "input": "${response.body}",
  "output": {
    "parsed": "user"
  }
}

Access with: ${user.id} (cleaner!)

Parsing Arrays

{
  "pipeline": [
    {
      "block": "HttpRequest",
      "input": {
        "url": "https://api.example.com/users",
        "method": "GET"
      },
      "output": "response"
    },
    {
      "block": "JsonParser",
      "input": "${response.body}",
      "output": {
        "parsed": "users"
      }
    }
  ],
  "assertions": {
    "users[0].id": { "gt": 0 }
  }
}

Error Handling

If parsing fails, the block returns an error:

{
  error: "JSON parse error: Unexpected token...",
  raw: "invalid json{]"
}

You can check for errors in assertions:

{
  "assertions": {
    "parsed.error": null
  }
}

Or assert success by checking the parsed data exists:

{
  "assertions": {
    "user.id": { "gt": 0 }
  }
}

Common Patterns

HTTP Request + Parse

{
  "pipeline": [
    {
      "block": "HttpRequest",
      "input": { "url": "${API_URL}/data", "method": "GET" },
      "output": "response"
    },
    {
      "block": "JsonParser",
      "input": "${response.body}",
      "output": { "parsed": "data" }
    }
  ]
}

Nested Data Extraction

{
  "pipeline": [
    {
      "block": "HttpRequest",
      "output": "response"
    },
    {
      "block": "JsonParser",
      "input": "${response.body}",
      "output": { "parsed": "apiResponse" }
    }
  ],
  "assertions": {
    "apiResponse.data.users[0].email": { "matches": ".*@.*" }
  }
}

Multiple Parse Operations

{
  "pipeline": [
    {
      "block": "HttpRequest",
      "input": { "url": "${API_URL}/user", "method": "GET" },
      "output": "userResponse"
    },
    {
      "block": "JsonParser",
      "input": "${userResponse.body}",
      "output": { "parsed": "user" }
    },
    {
      "block": "HttpRequest",
      "input": { "url": "${API_URL}/posts", "method": "GET" },
      "output": "postsResponse"
    },
    {
      "block": "JsonParser",
      "input": "${postsResponse.body}",
      "output": { "parsed": "posts" }
    }
  ],
  "assertions": {
    "user.id": 1,
    "posts[0].userId": 1
  }
}

Full Example

{
  "name": "JSON Parsing Test",
  "context": {
    "BASE_URL": "https://jsonplaceholder.typicode.com"
  },
  "tests": [{
    "id": "test-parse",
    "pipeline": [
      {
        "id": "fetch",
        "block": "HttpRequest",
        "input": {
          "url": "${BASE_URL}/users/1",
          "method": "GET"
        },
        "output": "response"
      },
      {
        "id": "parse",
        "block": "JsonParser",
        "input": "${response.body}",
        "output": {
          "parsed": "user"
        }
      }
    ],
    "assertions": {
      "response.status": 200,
      "user.id": 1,
      "user.name": { "matches": ".+" },
      "user.email": { "matches": ".*@.*" },
      "user.address.city": { "matches": ".+" }
    }
  }]
}

Tips

Always Use Object Output Format

Map parsed to a descriptive name for cleaner references:

// Bad - nested access
"output": "result"
// Access: ${result.parsed.user.id}

// Good - direct access
"output": { "parsed": "user" }
// Access: ${user.id}

Handle Parse Errors Gracefully

Check if parsing succeeded before making assertions:

{
  "assertions": {
    "data.id": { "gt": 0 }
  }
}

If parsed doesn’t exist (parse failed), assertion will fail with clear message.

Parse Before Validation

Always parse JSON before using validation blocks:

{
  "pipeline": [
    { "block": "HttpRequest", "output": "response" },
    {
      "block": "JsonParser",
      "input": "${response.body}",
      "output": { "parsed": "data" }
    },
    {
      "block": "ValidateContent",
      "input": { "from": "data.message", "as": "text" }
    }
  ]
}

When to Use

Use JsonParser when:

Parsing HTTP response bodies
Converting JSON strings to objects
Accessing nested JSON properties

Don’t use when:

Response is already an object (not common in SemanticTest)
Parsing streaming responses (use StreamParser)

Next Steps

HttpRequest

Make HTTP requests

ValidateContent

Validate parsed data

Get Started

Core Concepts

Blocks

Testing AI Systems

Advanced

Overview

Input Parameters

Required

Output Fields

On Success

On Failure

Examples

Basic Usage

Using String Input Format

Using Object Format (Recommended)

Parsing Arrays

Error Handling

Common Patterns

HTTP Request + Parse

Nested Data Extraction

Multiple Parse Operations

Full Example

Tips

When to Use

Next Steps

HttpRequest

ValidateContent

​Overview

​Input Parameters

​Required

​Output Fields

​On Success

​On Failure

​Examples

​Basic Usage

​Using String Input Format

​Using Object Format (Recommended)

​Parsing Arrays

​Error Handling

​Common Patterns

​HTTP Request + Parse

​Nested Data Extraction

​Multiple Parse Operations

​Full Example

​Tips

​When to Use

​Next Steps

HttpRequest

ValidateContent

Overview

Input Parameters

Required

Output Fields

On Success

On Failure

Examples

Basic Usage

Using String Input Format

Using Object Format (Recommended)

Parsing Arrays

Error Handling

Common Patterns

HTTP Request + Parse

Nested Data Extraction

Multiple Parse Operations

Full Example

Tips

When to Use

Next Steps