Null vs Missing Value Confidence Prompt

This prompt is for data quality engineers and pipeline builders who need to move beyond binary extraction. The core job is to classify every target field into one of three states: present with a value, present but empty/null, or genuinely absent from the source text. A simple extraction that returns null for both a missing field and an empty field creates a data quality nightmare downstream—you can't tell if the source was silent or explicitly blank. This prompt forces the model to make that distinction and provide a confidence score and evidence span for its classification.

Use this prompt when you are ingesting semi-structured or unstructured text into a system of record where null semantics matter. For example, a contract review pipeline needs to know if a 'termination date' field is missing from the document (high risk, needs escalation) versus present but left blank (explicitly open-ended). The prompt requires a defined [FIELD_SCHEMA] with field names and descriptions, the [SOURCE_TEXT] to analyze, and a [CONFIDENCE_THRESHOLD] for flagging uncertain classifications. It is designed to be wired into a validation harness that checks for conflation errors—specifically, that a missing field is never classified as empty, and an empty field is never classified as missing without explicit evidence.

Do not use this prompt for simple key-value extraction where null semantics are irrelevant, or when you cannot tolerate the extra token cost of tri-state classification. It is also not a replacement for a full entity resolution pipeline; it classifies the presence state of a field, not the identity of an entity. If your downstream system cannot distinguish between a missing value and an empty string, this prompt adds complexity without value. Before deploying, ensure your eval suite includes test cases for all three states, edge cases like whitespace-only values, and adversarial examples where the source text implies a value without stating it directly. Human review is mandatory for any classification that falls below the configured confidence threshold, especially for fields with regulatory or financial impact.

The following prompt template is designed to be copied directly into your prompt management system, IDE, or orchestration layer. It uses square-bracket placeholders for all dynamic inputs, making it safe to store in version control and inject at runtime. The template forces a strict tri-state classification—NULL (genuinely absent), EMPTY (present but empty), or UNREADABLE (present with unreadable content)—for each target field, preventing the common production failure where missing data and empty strings are conflated in downstream ingestion pipelines.

textCopy
You are a data quality classifier for extraction pipelines. Your task is to analyze the source text and determine the state of each target field.

## INPUT
Source Text:
"""
[SOURCE_TEXT]
"""

Target Fields:
[FIELD_LIST]

## CLASSIFICATION RULES
For each target field, classify its state as exactly one of:
- `NULL`: The field is genuinely absent from the source text. No mention, no implication, no placeholder exists.
- `EMPTY`: The field is present in the source but contains no meaningful value (e.g., an empty form field, a blank line, a placeholder like "N/A" or "--").
- `UNREADABLE`: The field is present but the value cannot be reliably read due to garbled text, OCR errors, corruption, truncation, or encoding issues.

## CONFIDENCE SCORING
For each classification, provide a confidence score from 0.0 to 1.0 where:
- 0.9-1.0: Clear, unambiguous evidence supports the classification.
- 0.7-0.89: Strong evidence with minor ambiguity.
- 0.5-0.69: Plausible classification but significant ambiguity exists.
- Below 0.5: Do not classify; mark as `AMBIGUOUS` with a note.

## EVIDENCE REQUIREMENT
For every classification, you MUST provide:
- An `evidence_span`: The exact substring from the source text that supports your classification, or an empty string if the evidence is the absence of any mention.
- An `evidence_rationale`: A one-sentence explanation of why this span supports the classification.

## OUTPUT SCHEMA
Return a JSON object with this exact structure:
{
  "fields": [
    {
      "field_name": "string",
      "classification": "NULL" | "EMPTY" | "UNREADABLE" | "AMBIGUOUS",
      "confidence": 0.0,
      "evidence_span": "string",
      "evidence_rationale": "string"
    }
  ],
  "overall_confidence": 0.0,
  "escalation_required": true | false,
  "escalation_reason": "string or null"
}

## CONSTRAINTS
[CONSTRAINTS]

## EXAMPLES
[EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

Adaptation guidance: Replace [SOURCE_TEXT] with the raw document or snippet under analysis. [FIELD_LIST] should be a JSON array of field names to classify, or a structured schema if your pipeline expects typed output. Use [CONSTRAINTS] to inject domain-specific rules—for example, "Treat the string 'N/A' as EMPTY, not NULL" or "Fields marked as PII require confidence >= 0.9." The [EXAMPLES] placeholder should contain 2-4 few-shot examples demonstrating the distinction between NULL, EMPTY, and UNREADABLE for your specific document type. Set [RISK_LEVEL] to HIGH for regulated domains, which should trigger mandatory human review when escalation_required is true. Before deploying, validate that your pipeline correctly handles the AMBIGUOUS classification—many downstream systems only expect the three primary states and will fail silently on unexpected values.

The Null vs Missing Value Confidence Prompt is designed to sit between raw text ingestion and structured record assembly. It should be called once per field per document, or batched as a single request with multiple field evaluations if your latency budget allows. The prompt expects a source text span and a target field name, and it returns a tri-state classification (NULL, EMPTY, VALUE) with a confidence score and an evidence span. This output is not a final record—it is a metadata annotation that downstream assembly logic uses to decide whether to populate, leave blank, or escalate a field.

Validation and Retry Logic: The model output must be validated against a strict JSON schema before it enters your pipeline. The schema should enforce that classification is exactly one of the three allowed strings, confidence is a float between 0.0 and 1.0, and evidence_span is a non-empty string that can be located in the original source text. If validation fails, implement a single retry with the error message injected into the prompt context. If the retry also fails, log the raw output and escalate the entire field to a human review queue rather than guessing. For high-volume pipelines, add a circuit breaker that halts processing if the validation failure rate exceeds 5% in a rolling window—this usually indicates a prompt drift or model behavior change.

Model Choice and Tool Use: This prompt works well with smaller, faster models (e.g., Claude Haiku, GPT-4o-mini) because the task is narrow and classification-focused. Avoid using large reasoning models unless you are also asking for a detailed justification. The prompt does not require external tools, retrieval, or function calling—it is a pure text-to-JSON classification task. However, you should wrap the call in application-level code that performs the evidence span lookup: after receiving the response, your harness should verify that the returned evidence_span substring exists in the original source text. If it does not, treat the result as a hallucination and escalate. This check is cheap, deterministic, and catches one of the most common failure modes: the model inventing a plausible but absent span.

Logging and Audit Trail: Every classification result should be logged with the input source text, the field name, the model's full response, the validation result, and the outcome (accepted, retried, escalated). This log becomes your audit trail for downstream consumers who need to understand why a field was populated, left null, or flagged as empty. For regulated domains, also log the model version and the prompt template hash so that every decision is traceable to a specific configuration. Do not rely on the model's confidence score alone for auditability—the evidence span and the application-level substring check provide the verifiable ground truth.

Integration with Record Assembly: After classification, your record assembly step should use the tri-state result to decide field population: VALUE classifications proceed to extraction and normalization; NULL classifications leave the field unpopulated with a missing annotation; EMPTY classifications populate the field with an empty string or domain-appropriate empty sentinel. Fields with confidence below your threshold (typically 0.7–0.85, depending on risk tolerance) should be routed to a review queue with the classification, evidence span, and source context attached. Avoid the common mistake of treating low-confidence NULL and low-confidence EMPTY the same way—they represent different underlying conditions and may require different reviewer instructions.