Claude JSON mode schema violation after adding new microservice field

Problem

When invoking Anthropic Claude in JSON mode from several microservices, the API intermittently returns a 400 Bad Request with a body similar to:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "JSON schema validation failed: field 'orderId' is required but missing."
  }
}

The failure appears after a new field orderId was added to the shared request schema. Existing services that do not populate this field start receiving the same validation error, causing downstream processing to stall.

Root Cause

Claude’s JSON mode validates the entire request payload against a static JSON schema that is generated at service start‑up. The schema is derived from the anthropic client library’s ClaudeMessage definition. Adding orderId to the shared MessagePayload struct triggered the following chain of events:

  1. Developers added orderId?: string (optional) to the TypeScript interface used by most services.
  2. The build pipeline regenerated the OpenAPI‑derived schema and redeployed the claude-client library.
  3. One microservice (billing-service) kept an older version of the client library that still expected the previous schema without orderId. When it sent a payload missing the new field, the server‑side validator considered the request malformed because the schema it was using now marks orderId as required (the library defaulted to required: true for non‑nullable fields).
  4. Because Claude’s JSON mode performs strict validation, any mismatch between the client‑side schema and the server‑side expectation results in an immediate rejection before the model processes the prompt.

In short, a version skew between microservices and the Claude client library caused the schema to diverge, making the new field effectively required for all callers.

Debug

The following steps were used to isolate the issue:

1. Inspect API response logs

2024-10-12T08:15:42.123Z INFO  request-id=7f3c9a2b-1e4d-4a9e-b8d2-9f6e7c3d5a1b
POST /v1/complete
Headers:
  Content-Type: application/json
  Anthropic-Version: 2023-06-01
Body:
{
  "model": "claude-2.1",
  "messages": [
    {"role":"user","content":"..."},
    {"role":"assistant","content":"..."}
  ],
  "metadata": {"orderId":"ORD-12345"}
}
Response:
400 Bad Request
{
  "type":"error",
  "error":{"type":"invalid_request_error","message":"JSON schema validation failed: field 'orderId' is required but missing."}
}

2. Compare client library versions

Microservice Client lib version Schema version
order-service 2.3.0 v2 (includes orderId)
billing-service 2.2.1 v1 (no orderId)
shipping-service 2.3.0 v2 (includes orderId)

3. Validate generated schema locally

# Using ajv-cli to validate a sample payload against the schema shipped with billing-service
ajv validate -s node_modules/anthropic-client/schema.json -d payload.json
ERROR: data should have required property 'orderId'

4. Capture network trace (optional)

sudo tcpdump -i any -s 0 -w claude.jsonmode.pcap port 443 and host api.anthropic.com
# Later, open in Wireshark and filter for HTTP/2 DATA frames containing the JSON body.

Solution

The fix required aligning all microservices to the same client library version and explicitly marking orderId as optional in the shared schema.

1. Update the shared TypeScript definition

Before:

// shared/message.ts
export interface MessagePayload {
  userId: string;
  // orderId was added later but not marked optional
  orderId: string; // <-- required by default
  content: string;
}

After:

// shared/message.ts
export interface MessagePayload {
  userId: string;
  orderId?: string; // <-- optional, matches business requirement
  content: string;
}

2. Regenerate the OpenAPI schema

# Using openapi-generator
openapi-generator-cli generate \
  -i src/openapi.yaml \
  -g typescript-fetch \
  -o generated-client \
  --additional-properties=useSingleRequestParameter=true

3. Bump the client library version across all services

# In each microservice repository
npm install anthropic-client@2.3.0 --save-exact
# Verify lockfile consistency
git diff package-lock.json

4. Redeploy the updated services

# Example using Kubernetes
kubectl set image deployment/billing-service billing-service=myrepo/billing-service:2.3.0
kubectl rollout status deployment/billing-service

Why the fix works

All services now generate payloads that conform to the same JSON schema where orderId is optional. Claude’s JSON mode validator receives a consistent contract, so missing the field no longer triggers a schema violation.

Verify

After deployment, run the following sanity checks:

1. Smoke test each service

curl -s -X POST https://api.anthropic.com/v1/complete \
  -H "Content-Type: application/json" \
  -d '{
        "model":"claude-2.1",
        "messages":[{"role":"user","content":"test"}],
        "metadata":{}
      }' | jq .
# Expected: 200 OK with a valid Claude response JSON.

2. Verify schema version at runtime

# Each service exposes /debug/schema endpoint
curl http://billing-service:8080/debug/schema | jq '.properties.orderId'
# Expected output: null (field not required)

3. Monitor error rate

# Prometheus query
rate(http_requests_total{service=~"order|billing|shipping",status="400"}[5m])
# Should be 0 after fix.

Prevent

  • Version lock the Claude client library across the entire monorepo using a single package.json workspace or a shared requirements.txt for Python.
  • Schema contract testing: add a CI job that validates a representative payload from each microservice against the generated schema using ajv (JS) or jsonschema (Python).
  • Automated compatibility checks: enforce that any change to the shared request model increments a SCHEMA_VERSION header, and reject deployments where the header does not match the server‑side expectation.
  • Observability: create a Grafana dashboard that tracks anthropic_json_schema_errors_total and alerts on spikes.
  • Documentation: keep the JSON schema definition in a version‑controlled schema.json file and reference it in API docs for all consuming services.

Related Topic Hub: LLM Systems Troubleshooting Hub

FAQ

  1. Why does the error appear only after adding a new field?
    The Claude client library treats non‑nullable fields as required by default. Adding a field without marking it optional changes the generated schema, causing older callers to miss the field and fail validation.
  2. Can I make Claude ignore unknown fields instead of rejecting the request?
    No. Claude’s JSON mode enforces strict schema validation; unknown or missing required fields result in a 400 error. The only way to relax validation is to adjust the schema itself.
  3. How do I know whether a field is required or optional in the generated schema?
    Run cat node_modules/anthropic-client/schema.json | jq '.properties.orderId'. If the property appears under required array, it is mandatory.
  4. Is there a way to version the JSON schema without redeploying all services?
    Yes. Claude supports a schema_version query parameter. By incrementing the version and deploying a compatibility shim that adds missing fields with default values, you can roll out changes gradually.
  5. What monitoring metric should I watch for future schema mismatches?
    Track anthropic_json_schema_errors_total (or equivalent custom metric) and set an alert threshold of >0 for a 5‑minute window.