{
  "openapi": "3.1.0",
  "info": {
    "title": "Who's Running API",
    "version": "1.0.0",
    "description": "Versioned API for Florida candidate directory clients. Public database-backed candidate and race surfaces exclude internally inactive duplicate rows, sample, SUPPRESSED, REJECTED, SPECIAL_DISTRICT_OPTIONAL, and MUNICIPAL_EXCLUDED filings. Public DTOs omit address fields, raw source payloads, source snapshots, admin notes, and paid visibility or ranking fields. County-source records take public precedence over matching state-source county records. Routine consumers should use /api/v1/metadata/data-refresh and pull after the published refresh window. Shared public DTO schemas are strict and reject unknown response fields until the public contract is intentionally updated."
  },
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Check deployment health",
        "description": "Returns service, database, environment, uptime, and non-secret deployment metadata. `deployment.commitHash` is null unless APP_COMMIT_HASH is configured.",
        "responses": {
          "200": {
            "description": "Health status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["status", "service", "apiVersion", "database", "sampleDataMode", "environment", "deployment", "uptimeSeconds", "checkedAt", "latencyMs"],
                  "properties": {
                    "status": { "type": "string", "enum": ["ok", "degraded"] },
                    "service": { "type": "string" },
                    "apiVersion": { "type": "string" },
                    "database": { "type": "string", "enum": ["not_configured", "ok", "error"] },
                    "databaseError": { "type": ["string", "null"] },
                    "sampleDataMode": { "type": "boolean" },
                    "databaseUrlConfigured": { "type": "boolean" },
                    "directUrlConfigured": { "type": "boolean" },
                    "environment": { "type": "string" },
                    "deployment": {
                      "type": "object",
                      "required": ["commitHash"],
                      "properties": {
                        "commitHash": { "type": ["string", "null"] }
                      }
                    },
                    "uptimeSeconds": { "type": "integer" },
                    "checkedAt": { "type": "string", "format": "date-time" },
                    "latencyMs": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/candidates": {
      "get": {
        "summary": "List candidate filings",
        "description": "Returns public-eligible candidate filing DTOs only. Database-backed results exclude internally inactive duplicate rows, sample, SUPPRESSED, REJECTED, SPECIAL_DISTRICT_OPTIONAL, and MUNICIPAL_EXCLUDED filings.",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "electionYear", "in": "query", "schema": { "type": "integer" } },
          { "name": "officeType", "in": "query", "schema": { "type": "string" } },
          { "name": "officeId", "in": "query", "schema": { "type": "string" } },
          { "name": "office", "in": "query", "schema": { "type": "string" } },
          { "name": "county", "in": "query", "schema": { "type": "string" } },
          { "name": "party", "in": "query", "schema": { "type": "string" } },
          { "name": "status", "in": "query", "schema": { "type": "string" } },
          { "name": "sourceType", "in": "query", "schema": { "type": "string" } },
          { "name": "jurisdictionLevel", "in": "query", "schema": { "type": "string" } },
          { "name": "sort", "in": "query", "schema": { "type": "string" } },
          { "name": "direction", "in": "query", "schema": { "type": "string", "enum": ["asc", "desc"] } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
          { "name": "pageSize", "in": "query", "schema": { "type": "integer", "default": 25, "maximum": 100 } }
        ],
        "responses": {
          "200": {
            "description": "Paginated candidate DTO list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PaginatedCandidateResponse" }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiError" }
              }
            }
          }
        }
      }
    },
    "/api/v1/candidates/{id}": {
      "get": {
        "summary": "Get a candidate filing profile",
        "description": "Returns one public-eligible candidate filing DTO. Public responses do not expose address fields, raw source payloads, source snapshots, or admin notes.",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "Candidate DTO",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": ["data"],
                  "properties": {
                    "data": { "$ref": "#/components/schemas/CandidateDto" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiError" }
              }
            }
          }
        }
      }
    },
    "/api/v1/races": {
      "get": {
        "summary": "List races",
        "description": "Returns races with at least one public-eligible candidate filing. Candidate counts include only public-eligible filings and public-scope office types.",
        "parameters": [
          { "name": "electionYear", "in": "query", "schema": { "type": "integer" } },
          { "name": "county", "in": "query", "schema": { "type": "string" } },
          { "name": "officeType", "in": "query", "schema": { "type": "string" } },
          { "name": "office", "in": "query", "schema": { "type": "string" } },
          { "name": "jurisdictionLevel", "in": "query", "schema": { "type": "string", "enum": ["FEDERAL", "STATE", "COUNTY"] } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
          { "name": "pageSize", "in": "query", "schema": { "type": "integer", "default": 25, "maximum": 100 } }
        ],
        "responses": {
          "200": {
            "description": "Paginated race DTO list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PaginatedRaceResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v1/races/{id}": {
      "get": {
        "summary": "Get race details",
        "description": "Returns race details with only public-eligible candidate filings attached.",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "Race detail DTO",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": ["data"],
                  "properties": {
                    "data": { "$ref": "#/components/schemas/RaceDetailDto" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiError" }
              }
            }
          }
        }
      }
    },
    "/api/v1/offices": {
      "get": {
        "summary": "List offices",
        "description": "Returns public-scope offices that have at least one public-eligible filing.",
        "responses": {
          "200": {
            "description": "Office DTO list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/OfficeDto" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jurisdictions": {
      "get": {
        "summary": "List jurisdictions",
        "description": "Returns public-scope jurisdictions that have at least one public-eligible filing.",
        "responses": {
          "200": {
            "description": "Jurisdiction DTO list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/JurisdictionDto" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/counties": {
      "get": {
        "summary": "List county source states",
        "description": "Returns all 67 Florida counties with source mapping status, connector metadata, freshness timestamps, and a derived count of currently public active county-source filings.",
        "responses": {
          "200": {
            "description": "County DTO list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "countyName",
                          "sourceUrl",
                          "sourceType",
                          "connectorType",
                          "status",
                          "freshnessStatus",
                          "lastCheckedAt",
                          "lastSuccessfulImportAt",
                          "manualReviewRequired",
                          "publicFilingCount"
                        ],
                        "properties": {
                          "countyName": { "type": "string" },
                          "sourceUrl": { "type": ["string", "null"], "format": "uri" },
                          "sourceType": { "type": "string" },
                          "connectorType": { "type": "string" },
                          "status": { "type": "string" },
                          "freshnessStatus": {
                            "type": "string",
                            "enum": [
                              "CURRENT",
                              "STALE",
                              "NO_SUCCESSFUL_IMPORT",
                              "NOT_REFRESH_TRACKED"
                            ],
                            "description": "Derived freshness state for automated county source imports. This is not a completeness guarantee."
                          },
                          "lastCheckedAt": { "type": ["string", "null"], "format": "date-time" },
                          "lastSuccessfulImportAt": { "type": ["string", "null"], "format": "date-time" },
                          "manualReviewRequired": { "type": "boolean" },
                          "publicFilingCount": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "Derived count of public, active county-source filings. This is not a completeness guarantee."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/metadata/data-refresh": {
      "get": {
        "summary": "Get public data refresh policy",
        "description": "Returns the published daily refresh window, recommended API consumer pull time, source strategy, and latest ingestion run timestamps.",
        "responses": {
          "200": {
            "description": "Data refresh metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "cadence",
                        "timezone",
                        "scheduledStartLocal",
                        "expectedCompleteLocal",
                        "recommendedConsumerPullAfterLocal",
                        "publicLabel",
                        "consumerLabel",
                        "sourceStrategy",
                        "implementationStatus",
                        "checkedAt",
                        "latestIngestionRun",
                        "latestSuccessfulIngestionRun"
                      ],
                      "properties": {
                        "cadence": { "type": "string", "enum": ["DAILY"] },
                        "timezone": { "type": "string", "enum": ["America/New_York"] },
                        "scheduledStartLocal": { "type": "string", "example": "06:00" },
                        "expectedCompleteLocal": { "type": "string", "example": "07:00" },
                        "recommendedConsumerPullAfterLocal": { "type": "string", "example": "07:15" },
                        "publicLabel": { "type": "string" },
                        "consumerLabel": { "type": "string" },
                        "sourceStrategy": { "type": "string" },
                        "implementationStatus": { "type": "string", "enum": ["MANUAL", "SCHEDULED", "HYBRID"] },
                        "checkedAt": { "type": "string", "format": "date-time" },
                        "latestIngestionRun": {
                          "type": ["object", "null"],
                          "required": ["sourceName", "status", "startedAt", "finishedAt", "rowsProcessed", "rowsCreated", "rowsUpdated"],
                          "properties": {
                            "sourceName": { "type": "string" },
                            "status": { "type": "string" },
                            "startedAt": { "type": "string", "format": "date-time" },
                            "finishedAt": { "type": ["string", "null"], "format": "date-time" },
                            "rowsProcessed": { "type": "integer" },
                            "rowsCreated": { "type": "integer" },
                            "rowsUpdated": { "type": "integer" }
                          }
                        },
                        "latestSuccessfulIngestionRun": {
                          "type": ["object", "null"],
                          "required": ["sourceName", "status", "startedAt", "finishedAt", "rowsProcessed", "rowsCreated", "rowsUpdated"],
                          "properties": {
                            "sourceName": { "type": "string" },
                            "status": { "type": "string" },
                            "startedAt": { "type": "string", "format": "date-time" },
                            "finishedAt": { "type": ["string", "null"], "format": "date-time" },
                            "rowsProcessed": { "type": "integer" },
                            "rowsCreated": { "type": "integer" },
                            "rowsUpdated": { "type": "integer" }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/admin/data-quality/unknowns": {
      "get": {
        "summary": "Summarize public UNKNOWN party and status rows",
        "description": "Admin-only endpoint. Requires `x-admin-token` when ADMIN_AUTH_SECRET is configured. Returns source-precedence-deduped public candidate rows whose party or normalized status is UNKNOWN, grouped by raw source value, source, office, and county. Used for parser-policy and source-review decisions, not unsourced manual candidate fact changes.",
        "responses": {
          "200": {
            "description": "Unknown data quality summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": ["checkedAt", "publicRowsScanned", "unknownParties", "unknownStatuses"],
                      "properties": {
                        "checkedAt": { "type": "string", "format": "date-time" },
                        "publicRowsScanned": { "type": "integer" },
                        "unknownParties": { "$ref": "#/components/schemas/UnknownDataQualityFieldSummary" },
                        "unknownStatuses": { "$ref": "#/components/schemas/UnknownDataQualityFieldSummary" }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "description": "Unauthorized" },
          "503": { "description": "Database unavailable" }
        }
      }
    },
    "/api/v1/admin/ingestion/florida-doe/run": {
      "post": {
        "summary": "Run Florida DOE import",
        "description": "Admin-only endpoint. Requires `x-admin-token` when ADMIN_AUTH_SECRET is configured and body `{ \"confirmImport\": true }`. Scheduled runs should pass `scope: \"state-and-federal\"`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["confirmImport"],
                "properties": {
                  "confirmImport": { "type": "boolean", "const": true },
                  "scope": { "type": "string", "enum": ["all", "state-and-federal"], "default": "all" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Import result" },
          "400": { "description": "Validation error" }
        }
      }
    },
    "/api/v1/admin/ingestion/florida-doe/source-link-repair": {
      "post": {
        "summary": "Repair Florida DOE source links",
        "description": "Admin-only maintenance endpoint. Requires `x-admin-token` when ADMIN_AUTH_SECRET is configured and body `{ \"confirmRepair\": true }`. Repairs stale DOE filing source links that point to bulk export/download URLs by moving matching filings to official candidate detail source URLs.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["confirmRepair"],
                "properties": {
                  "confirmRepair": { "type": "boolean", "const": true },
                  "limit": { "type": "integer", "minimum": 1, "maximum": 500 }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Source-link repair result" },
          "400": { "description": "Validation error" }
        }
      }
    },
    "/api/v1/admin/ingestion/counties/{connectorId}/run": {
      "post": {
        "summary": "Run an official county connector import",
        "description": "Admin-only endpoint. Requires `x-admin-token` when ADMIN_AUTH_SECRET is configured and body `{ \"confirmImport\": true }`. Records whose sourceType is not COUNTY are rejected.",
        "parameters": [{ "name": "connectorId", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["confirmImport"],
                "properties": {
                  "confirmImport": { "type": "boolean", "const": true }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Connector import result" },
          "400": { "description": "Validation error" },
          "404": { "description": "Connector not found" }
        }
      }
    },
    "/api/v1/metadata/election-years": {
      "get": {
        "summary": "List election years",
        "responses": {
          "200": {
            "description": "Election years",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "type": "integer" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/metadata/statuses": {
      "get": {
        "summary": "List candidate statuses",
        "responses": {
          "200": {
            "description": "Statuses",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "ACTIVE",
                          "FILED",
                          "QUALIFIED",
                          "WITHDRAWN",
                          "INACTIVE",
                          "DID_NOT_QUALIFY",
                          "ELECTED",
                          "DEFEATED",
                          "UNOPPOSED",
                          "DISQUALIFIED",
                          "TRANSFERRED_TO_LOCAL",
                          "REMOVED",
                          "REDESIGNATED",
                          "DECEASED",
                          "UNKNOWN"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/metadata/office-types": {
      "get": {
        "summary": "List public office types",
        "description": "Returns public-scope office types only. Hidden municipal and optional special-district buckets are excluded.",
        "responses": {
          "200": {
            "description": "Office types",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "FEDERAL",
                          "STATEWIDE",
                          "STATE_LEGISLATIVE",
                          "STATE_JUDICIAL",
                          "STATE_ATTORNEY",
                          "PUBLIC_DEFENDER",
                          "COUNTY_CONSTITUTIONAL",
                          "COUNTY_COMMISSION",
                          "COUNTY_JUDICIAL",
                          "SCHOOL_BOARD",
                          "SCHOOL_SUPERINTENDENT",
                          "UNKNOWN"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ApiError": {
        "type": "object",
        "additionalProperties": false,
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" },
              "details": {}
            }
          }
        }
      },
      "Pagination": {
        "type": "object",
        "additionalProperties": false,
        "required": ["page", "pageSize", "total", "totalPages"],
        "properties": {
          "page": { "type": "integer", "minimum": 1 },
          "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 },
          "total": { "type": "integer", "minimum": 0 },
          "totalPages": { "type": "integer", "minimum": 1 }
        }
      },
      "OfficeType": {
        "type": "string",
        "enum": [
          "FEDERAL",
          "STATEWIDE",
          "STATE_LEGISLATIVE",
          "STATE_JUDICIAL",
          "STATE_ATTORNEY",
          "PUBLIC_DEFENDER",
          "COUNTY_CONSTITUTIONAL",
          "COUNTY_COMMISSION",
          "COUNTY_JUDICIAL",
          "SCHOOL_BOARD",
          "SCHOOL_SUPERINTENDENT",
          "UNKNOWN"
        ]
      },
      "JurisdictionLevel": {
        "type": "string",
        "enum": ["FEDERAL", "STATE", "COUNTY", "DISTRICT", "SCHOOL_DISTRICT", "UNKNOWN"]
      },
      "PartyAffiliation": {
        "type": "string",
        "enum": [
          "DEMOCRATIC",
          "REPUBLICAN",
          "NO_PARTY_AFFILIATION",
          "NONPARTISAN",
          "LIBERTARIAN",
          "GREEN",
          "INDEPENDENT",
          "OTHER",
          "UNKNOWN"
        ]
      },
      "BallotDesignation": {
        "type": "string",
        "enum": ["WRITE_IN"],
        "description": "Source-backed ballot designation. WRITE_IN is not a party affiliation."
      },
      "CandidateStatus": {
        "type": "string",
        "enum": [
          "ACTIVE",
          "FILED",
          "QUALIFIED",
          "WITHDRAWN",
          "INACTIVE",
          "DID_NOT_QUALIFY",
          "ELECTED",
          "DEFEATED",
          "UNOPPOSED",
          "DISQUALIFIED",
          "TRANSFERRED_TO_LOCAL",
          "REMOVED",
          "REDESIGNATED",
          "DECEASED",
          "UNKNOWN"
        ]
      },
      "SourceType": {
        "type": "string",
        "enum": ["STATE", "FEC", "COUNTY", "MANUAL_UPLOAD", "SAMPLE_DATA"]
      },
      "ManualReviewStatus": {
        "type": "string",
        "enum": ["PENDING", "REVIEWED", "NEEDS_REVIEW", "SUPPRESSED", "REJECTED"]
      },
      "OfficeDto": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "name", "type"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "type": { "$ref": "#/components/schemas/OfficeType" }
        }
      },
      "OfficeReference": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "name", "type"],
        "properties": {
          "id": { "type": ["string", "null"] },
          "name": { "type": "string" },
          "type": { "$ref": "#/components/schemas/OfficeType" }
        }
      },
      "JurisdictionDto": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "name", "level", "county"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "level": { "$ref": "#/components/schemas/JurisdictionLevel" },
          "county": { "type": ["string", "null"] }
        }
      },
      "JurisdictionReference": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "name", "level", "county"],
        "properties": {
          "id": { "type": ["string", "null"] },
          "name": { "type": "string" },
          "level": { "$ref": "#/components/schemas/JurisdictionLevel" },
          "county": { "type": ["string", "null"] }
        }
      },
      "SourceAttribution": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "sourceName",
          "sourceUrl",
          "sourceType",
          "lastSeenAt",
          "lastVerifiedAt",
          "sourceUpdatedAt"
        ],
        "properties": {
          "sourceName": { "type": "string" },
          "sourceUrl": { "type": ["string", "null"], "format": "uri" },
          "sourceType": { "$ref": "#/components/schemas/SourceType" },
          "lastSeenAt": { "type": "string", "format": "date-time" },
          "lastVerifiedAt": { "type": ["string", "null"], "format": "date-time" },
          "sourceUpdatedAt": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "CandidateFieldSources": {
        "type": "object",
        "additionalProperties": false,
        "description": "Official source attribution for displayed candidate fields that may be filled from a matched secondary source when the primary public filing omits the value.",
        "required": ["party", "normalizedStatus"],
        "properties": {
          "party": { "$ref": "#/components/schemas/SourceAttribution" },
          "normalizedStatus": { "$ref": "#/components/schemas/SourceAttribution" }
        }
      },
      "UnknownDataQualityLowerPriorityMatch": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "matchType",
          "filingId",
          "candidateName",
          "sourceName",
          "sourceUrl",
          "sourceType",
          "rawParty",
          "party",
          "ballotDesignation",
          "rawStatus",
          "normalizedStatus"
        ],
        "properties": {
          "matchType": { "type": "string", "enum": ["EXACT_PUBLIC_KEY", "NEAR_NAME"] },
          "filingId": { "type": "string" },
          "candidateName": { "type": "string" },
          "sourceName": { "type": "string" },
          "sourceUrl": { "type": ["string", "null"], "format": "uri" },
          "sourceType": { "$ref": "#/components/schemas/SourceType" },
          "rawParty": { "type": ["string", "null"] },
          "party": { "$ref": "#/components/schemas/PartyAffiliation" },
          "ballotDesignation": { "oneOf": [{ "$ref": "#/components/schemas/BallotDesignation" }, { "type": "null" }] },
          "rawStatus": { "type": ["string", "null"] },
          "normalizedStatus": { "$ref": "#/components/schemas/CandidateStatus" }
        }
      },
      "UnknownDataQualityExample": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "filingId",
          "candidateName",
          "officeName",
          "officeType",
          "electionYear",
          "jurisdictionName",
          "county",
          "district",
          "groupOrSeat",
          "rawParty",
          "party",
          "rawStatus",
          "normalizedStatus",
          "sourceName",
          "sourceUrl",
          "sourceType",
          "lastSeenAt",
          "lastVerifiedAt",
          "sourceUpdatedAt",
          "lowerPriorityMatches"
        ],
        "properties": {
          "filingId": { "type": "string" },
          "candidateName": { "type": "string" },
          "officeName": { "type": "string" },
          "officeType": { "$ref": "#/components/schemas/OfficeType" },
          "electionYear": { "type": "integer" },
          "jurisdictionName": { "type": "string" },
          "county": { "type": ["string", "null"] },
          "district": { "type": ["string", "null"] },
          "groupOrSeat": { "type": ["string", "null"] },
          "rawParty": { "type": ["string", "null"] },
          "party": { "$ref": "#/components/schemas/PartyAffiliation" },
          "rawStatus": { "type": ["string", "null"] },
          "normalizedStatus": { "$ref": "#/components/schemas/CandidateStatus" },
          "sourceName": { "type": "string" },
          "sourceUrl": { "type": ["string", "null"], "format": "uri" },
          "sourceType": { "$ref": "#/components/schemas/SourceType" },
          "lastSeenAt": { "type": "string", "format": "date-time" },
          "lastVerifiedAt": { "type": ["string", "null"], "format": "date-time" },
          "sourceUpdatedAt": { "type": ["string", "null"], "format": "date-time" },
          "lowerPriorityMatches": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/UnknownDataQualityLowerPriorityMatch" }
          }
        }
      },
      "UnknownDataQualityGroup": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "rawValue",
          "rawValueLabel",
          "sourceName",
          "sourceType",
          "officeName",
          "officeType",
          "county",
          "count",
          "knownLowerPrioritySourceCount",
          "resolutionHint",
          "examples"
        ],
        "properties": {
          "rawValue": { "type": ["string", "null"] },
          "rawValueLabel": { "type": "string" },
          "sourceName": { "type": "string" },
          "sourceType": { "$ref": "#/components/schemas/SourceType" },
          "officeName": { "type": "string" },
          "officeType": { "$ref": "#/components/schemas/OfficeType" },
          "county": { "type": ["string", "null"] },
          "count": { "type": "integer" },
          "knownLowerPrioritySourceCount": { "type": "integer" },
          "resolutionHint": {
            "type": "string",
            "enum": [
              "SOURCE_FIELD_BLANK_OR_MISSING",
              "UNNORMALIZED_SOURCE_VALUE",
              "LOWER_PRIORITY_SOURCE_HAS_VALUE"
            ]
          },
          "examples": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/UnknownDataQualityExample" }
          }
        }
      },
      "UnknownDataQualityFieldSummary": {
        "type": "object",
        "additionalProperties": false,
        "required": ["count", "knownLowerPrioritySourceCount", "groups"],
        "properties": {
          "count": { "type": "integer" },
          "knownLowerPrioritySourceCount": { "type": "integer" },
          "groups": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/UnknownDataQualityGroup" }
          }
        }
      },
      "CandidateDto": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "filingId",
          "candidateName",
          "office",
          "electionYear",
          "jurisdiction",
          "district",
          "groupOrSeat",
          "party",
          "ballotDesignation",
          "normalizedStatus",
          "originalStatus",
          "reviewStatus",
          "isSampleData",
          "isCandidateVerified",
          "attribution",
          "fieldSources",
          "publicNotice"
        ],
        "properties": {
          "id": { "type": "string" },
          "filingId": { "type": "string" },
          "candidateName": {
            "type": "string",
            "description": "Public display label, usually Last, First when the source name can be safely parsed."
          },
          "office": { "$ref": "#/components/schemas/OfficeReference" },
          "electionYear": { "type": "integer" },
          "jurisdiction": { "$ref": "#/components/schemas/JurisdictionReference" },
          "district": { "type": ["string", "null"] },
          "groupOrSeat": { "type": ["string", "null"] },
          "party": { "$ref": "#/components/schemas/PartyAffiliation" },
          "ballotDesignation": {
            "oneOf": [{ "$ref": "#/components/schemas/BallotDesignation" }, { "type": "null" }],
            "description": "Source-backed ballot designation such as WRITE_IN. This field is separate from party affiliation."
          },
          "normalizedStatus": { "$ref": "#/components/schemas/CandidateStatus" },
          "originalStatus": { "type": ["string", "null"] },
          "reviewStatus": { "$ref": "#/components/schemas/ManualReviewStatus" },
          "isSampleData": { "type": "boolean" },
          "isCandidateVerified": { "type": "boolean" },
          "attribution": {
            "$ref": "#/components/schemas/SourceAttribution",
            "description": "Primary public filing source for this candidate row."
          },
          "fieldSources": { "$ref": "#/components/schemas/CandidateFieldSources" },
          "publicNotice": {
            "type": "string",
            "example": "Imported from public election records. Not candidate-verified."
          }
        }
      },
      "RaceDto": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "slug",
          "office",
          "electionYear",
          "jurisdiction",
          "district",
          "groupOrSeat",
          "candidateCount"
        ],
        "properties": {
          "id": { "type": "string" },
          "slug": { "type": "string" },
          "office": { "$ref": "#/components/schemas/OfficeReference" },
          "electionYear": { "type": "integer" },
          "jurisdiction": { "$ref": "#/components/schemas/JurisdictionReference" },
          "district": { "type": ["string", "null"] },
          "groupOrSeat": { "type": ["string", "null"] },
          "candidateCount": { "type": "integer", "minimum": 0 }
        }
      },
      "RaceDetailDto": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "slug",
          "office",
          "electionYear",
          "jurisdiction",
          "district",
          "groupOrSeat",
          "candidateCount",
          "candidates"
        ],
        "properties": {
          "id": { "type": "string" },
          "slug": { "type": "string" },
          "office": { "$ref": "#/components/schemas/OfficeReference" },
          "electionYear": { "type": "integer" },
          "jurisdiction": { "$ref": "#/components/schemas/JurisdictionReference" },
          "district": { "type": ["string", "null"] },
          "groupOrSeat": { "type": ["string", "null"] },
          "candidateCount": { "type": "integer", "minimum": 0 },
          "candidates": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/CandidateDto" }
          }
        }
      },
      "PaginatedCandidateResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["data", "pagination"],
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/CandidateDto" }
          },
          "pagination": { "$ref": "#/components/schemas/Pagination" }
        }
      },
      "PaginatedRaceResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["data", "pagination"],
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/RaceDto" }
          },
          "pagination": { "$ref": "#/components/schemas/Pagination" }
        }
      }
    }
  }
}