Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.semantictest.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
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

ParameterTypeDescription
bodystringJSON string to parse

​
Output Fields

​
On Success

FieldTypeDescription
parsedobject/arrayThe parsed JSON data

​
On Failure

FieldTypeDescription
errorstringError message describing parse failure
rawstringOriginal 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:
  1. HttpRequest returns: { body: '{"id": 1, "name": "John"}' }
  2. JsonParser parses to: { parsed: { id: 1, name: "John" } }
  3. Stored in DataBus as: user = { id: 1, name: "John" }
  4. 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} 
{
  "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

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}
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.
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