Manage Case State Schemas

Overview

The case state schema defines the expected structure of the JSON state returned for each case by the external API. It helps API clients, case views, and derived keywords agree on where important information lives.

Use a case state schema when case data must be inspected, corrected, displayed, searched, or reused by external integrations.

Questions This Article Answers

• What belongs in case state?
• How is case state different from run output?
• How should schema fields be named and grouped?
• How do derived keyword mappings reference case state?
• How should schema changes be rolled out?

Case State vs. Output Schema

Reindeer exposes two related schemas through agent configuration:

• case_state_json_schema: describes persistent case data.
• output_model_json_schema: describes the structured output produced by a run.

Use the case state schema for data that should remain attached to the case after the run, support UI display, or be corrected by users. Use the output model schema for the agent's run result.

Schema Design Principles

Design the schema around stable business concepts, not temporary processing details.

Good schema fields are:

• Named using clear business language.
• Grouped by domain area, such as classification, customer, invoice, validation, or review.
• Typed consistently.
• Small enough to support targeted updates.
• Useful for UI display, review, automation, or search.

Example:

{
  "type": "object",
  "properties": {
    "classification": {
      "type": "object",
      "properties": {
        "document_type": { "type": "string" },
        "confidence": { "type": "number" }
      }
    },
    "review": {
      "type": "object",
      "properties": {
        "required": { "type": "boolean" },
        "reason": { "type": ["string", "null"] }
      }
    }
  }
}

Derived Keywords

Case keyword mappings can derive searchable or indexable values from case state. Each mapping has a keyword key and a JSONPath into the case state.

Example:

[
  {
    "key": "document_type",
    "path": "$.classification.document_type"
  },
  {
    "key": "review_required",
    "path": "$.review.required"
  }
]

Keyword paths should resolve to scalar values, such as strings, numbers, booleans, constants, or enum values. Use field names, array wildcards, or array indexes only.

Good keyword paths:

• $.classification.document_type
• $.review.required
• $.customer.country
• $.invoice.currency

Avoid keyword paths that resolve to full objects, large arrays, raw text, or values that may be missing on most cases.

Schema Compatibility

Schema changes affect future runs and API responses. Existing cases may still contain state written before the change.

When changing a schema:

1. Add new fields before removing old ones.
2. Keep old display paths available until active cases have migrated.
3. Use nullable fields when a value may be unknown.
4. Avoid renaming fields unless you can update display settings, keyword mappings, and external integrations at the same time.
5. Test representative cases before using the updated schema in production.

Operational Checklist

Before using a new or changed schema, confirm:

• Required business fields are represented.
• Nullable fields are used where values may be unknown.
• Display settings point to existing schema paths.
• Keyword mappings resolve to scalar values.
• External integrations can tolerate missing or newly added fields.
• Sensitive values are omitted, masked, or protected by the intended access model.

Common Mistakes

• Putting large raw documents or full email bodies in case state.
• Using inconsistent names for the same concept.
• Storing user-facing status as free text when an enum would be safer.
• Changing a schema path without updating display settings.
• Using nested structures that are hard to patch safely.