JSON Mode

JSON Mode Guide

Masker API can process entire JSON structures, recursively scanning and redacting PII in all string values while preserving the JSON structure.

---

How It Works

JSON mode processes JSON objects and arrays recursively:

• Only string values are scanned for PII
• JSON structure is preserved
• Non-string values (numbers, booleans, null) remain unchanged
• Arrays are processed recursively

---

Example

Input:

{
  "user": {
    "name": "John Doe",
    "email": "john@example.com",
    "age": 30,
    "phone": "555-123-4567",
    "tags": ["developer", "john@example.com"]
  }
}

Request:

curl -X POST "https://masker.kikuai.dev/v1/redact" \
  -H "Content-Type: application/json" \
  -d '{
    "json": {
      "user": {
        "name": "John Doe",
        "email": "john@example.com",
        "age": 30,
        "phone": "555-123-4567",
        "tags": ["developer", "john@example.com"]
      }
    },
    "mode": "placeholder"
  }'

Response:

{
  "redacted_text": null,
  "redacted_json": {
    "user": {
      "name": "<PERSON>",
      "email": "<EMAIL>",
      "age": 30,
      "phone": "<PHONE>",
      "tags": ["developer", "<EMAIL>"]
    }
  },
  "items": [
    {
      "entity_type": "PERSON",
      "path": "user.name",
      "start": 0,
      "end": 8,
      "score": 0.85
    },
    {
      "entity_type": "EMAIL",
      "path": "user.email",
      "start": 0,
      "end": 16,
      "score": 1.0
    },
    {
      "entity_type": "PHONE",
      "path": "user.phone",
      "start": 0,
      "end": 12,
      "score": 1.0
    },
    {
      "entity_type": "EMAIL",
      "path": "user.tags[1]",
      "start": 0,
      "end": 16,
      "score": 1.0
    }
  ],
  "processing_time_ms": 23.46
}

---

Key Features

Structure Preservation

• JSON structure is completely preserved
• Only string values are modified
• Numbers, booleans, null values remain unchanged

Path Tracking

Each detected entity includes a path field showing its location:

• "user.name" - Object property
• "user.tags[1]" - Array element
• "data.users[0].email" - Nested structure

Recursive Processing

• Nested objects are processed recursively
• Arrays are processed element by element
• Deep nesting is supported

---

Use Cases

1. Anonymize User Data

user_data = {
    "id": 12345,
    "name": "John Doe",
    "email": "john@example.com",
    "profile": {
        "phone": "555-123-4567",
        "address": "123 Main St"
    }
}

# Anonymize before AI analysis
response = requests.post(
    "https://masker.kikuai.dev/v1/redact",
    json={"json": user_data, "mode": "placeholder"}
)

2. Process Form Submissions

form_data = {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "message": "Need help with my account",
    "metadata": {
        "source": "web",
        "timestamp": "2025-11-27"
    }
}

# Clean before LLM processing
cleaned = requests.post(
    "https://masker.kikuai.dev/v1/redact",
    json={"json": form_data, "mode": "placeholder"}
).json()["redacted_json"]

---

Entity Filtering in JSON Mode

You can filter which entity types to redact:

{
  "json": {
    "user": {
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "555-123-4567"
    }
  },
  "mode": "placeholder",
  "entities": ["EMAIL"]
}

Result: Only email addresses are redacted, names and phones remain unchanged.

---

Limitations

• Maximum payload size: 64KB
• Maximum nesting depth: No hard limit (but very deep nesting may impact performance)
• Array size: No hard limit (but large arrays may impact performance)

---

Best Practices

1. Use entity filtering when you only need specific PII types
2. Process large JSON in chunks if it exceeds 64KB
3. Check processing_time_ms to monitor performance
4. Use path field to track where PII was found

---

Last Updated: 2025-11-27