---
name: output-schema-formatter
description: Expert knowledge of the disambiguation result JSON schema. Provides formatting rules, field requirements, and examples for structuring author disambiguation results correctly.
---

# Output Schema

## What You Must Include

```json
{
  "status": "success|ambiguous|not_found|error",
  "author_candidates": [],
  "search_summary": {},
  "comments": "string"
}
```

## What Each Candidate Should Look Like

```json
{
  "rank": 1,
  "author": {
    "openalex_id": "A5074091984",
    "openalex_url": "https://openalex.org/A5074091984",
    "name": "Author Name",
    "orcid": "0000-0002-XXXX-XXXX" | null,
    "institution": "Institution Name" | null,
    "works_count": 156,
    "cited_by_count": 21847
  },
  "evidence": ["ORCID match", "Institution match", ...],
  "concerns": []
}
```

**Must include in `author`**: openalex_id, openalex_url, name, works_count, cited_by_count  
**Can be null**: orcid, institution

## Search Summary

```json
{
  "embo_found": true|false,
  "orcid_source": "user provided|EMBO people.embo.org|OpenAlex profile|not available",
  "candidates_evaluated": 3,
  "disambiguation_needed": true|false
}
```

## What Status Means

| Status | What to include | Extra fields | When to use |
|--------|----------------|--------------|-------------|
| success | 1 candidate, rank=1 | — | Found a match! Even if not 100% certain, if it's the best match, use success |
| ambiguous | 2+ candidates, ranked | message, recommendation | Multiple strong candidates, can't decide which is right |
| not_found | empty `[]` | message, possible_reasons, recommendation | Searched but found nothing matching the name |
| error | empty `[]` | message, error | API error or technical failure during search |

**Rule of thumb**: If you found someone with the right name and reasonable context match → use "success"!

## Important Notes

- `openalex_id`: Just the ID part like "A5074091984", not the full URL
- `evidence`: Need at least one piece of evidence per candidate (can be simple like "Name match", "Institution match")
- `comments`: Always explain your reasoning (never leave this empty)
- **CRITICAL**: If you found ANY candidate matches, YOU MUST include them in `author_candidates` array! Never return an empty array if you found someone. Set status="success" if you found a match.

The output schema to be used can be found below

DISAMBIGUATION_RESULT_SCHEMA = {
    "type": "object",
    "properties": {
        # Status (required)
        "status": {
            "type": "string",
            "enum": ["success", "ambiguous", "not_found", "error"],
            "description": "Status of the disambiguation"
        },

        # Author candidates (always present, may be empty array)
        "author_candidates": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "rank": {
                        "type": "integer",
                        "description": "Rank of this candidate (1 = most likely)"
                    },
                    "author": {
                        "type": "object",
                        "properties": {
                            "openalex_id": {"type": "string"},
                            "openalex_url": {"type": "string"},
                            "name": {"type": "string"},
                            "orcid": {"type": ["string", "null"]},
                            "institution": {"type": ["string", "null"]},
                            "works_count": {"type": "integer"},
                            "cited_by_count": {"type": "integer"},
                         },
                        "required": ["openalex_id", "openalex_url", "name", "works_count", "cited_by_count"]
                    },
                    "evidence": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "List of evidence supporting this match"
                    },
                    "concerns": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "List of concerns or red flags about this match"
                    }
                },
                "required": ["rank", "author", "evidence"]
            },
            "description": "List of candidate authors (ordered by rank, may be empty)"
        },

        # Search summary (required)
        "search_summary": {
            "type": "object",
            "properties": {
                "embo_found": {"type": "boolean"},
                "orcid_source": {"type": "string"},
                "candidates_evaluated": {"type": "integer"},
                "disambiguation_needed": {"type": "boolean"}
            },
            "required": ["embo_found", "orcid_source", "candidates_evaluated", "disambiguation_needed"],
            "description": "Summary of search process"
        },

        # Message (optional - used for error, not_found, ambiguous cases)
        "message": {
            "type": "string",
            "description": "Human-readable message about the result"
        },

        # Error details (optional - used for error cases)
        "error": {
            "type": "string",
            "description": "Error message if status is 'error'"
        },

        # Additional info (optional - used for not_found cases)
        "possible_reasons": {
            "type": "array",
            "items": {"type": "string"},
            "description": "Possible reasons why no match was found"
        },
        "recommendation": {
            "type": "string",
            "description": "Recommendation for next steps"
        },

        # Comments (required)
        "comments": {
            "type": "string",
            "description": "Detailed process comments and reasoning"
        }
    },
    "required": ["status", "author_candidates", "search_summary", "comments"]
}
