{
  "openapi": "3.1.0",
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "info": {
    "title": "LocalFactBook public data and correction API",
    "version": "0.1.0",
    "description": "Read-only access to approved publications, with a separate bounded correction-report intake. Preview statistics visible in development HTML are not automatically eligible for this API. Responses use current rights checks; no API key is required for these public reads. Best-effort edge-IP rate limit: 60 requests per 60 seconds. This is not a global or account quota guarantee."
  },
  "servers": [
    {
      "url": "https://localfactbook.com",
      "description": "Production origin"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "Publications",
      "description": "Approved publication data and source permissions."
    }
  ],
  "paths": {
    "/api/v1/corrections": {
      "get": {
        "operationId": "listPublicCorrections",
        "summary": "Read audited public resolutions for the current approved publication.",
        "description": "Returns only curated public resolutions with completed propagation evidence for the current QA-approved publication and current source display rights. Raw reports, evidence submitted by readers and operator identities are never returned. After rollback or a later release, older resolutions stay private until reviewed for the active publication. Initial inventory is bounded at1000 records.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "after",
            "in": "query",
            "description": "Opaque next cursor for this unchanged request and limit; maximum2048 characters. Never a record ID or authorization.",
            "schema": {
              "type": "string",
              "maxLength": 2048,
              "pattern": "^[A-Za-z0-9_-]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public resolution entries, opaque cursor and approved publication identity.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CorrectionHistoryResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        }
      },
      "post": {
        "operationId": "submitCorrectionReport",
        "summary": "Record source-linked evidence for human review without changing facts.",
        "description": "The production same-origin correction form submits bounded JSON (24,000 bytes maximum), an available geography/metric pair and public HTTPS evidence. Server generates receipt identity/time. No contact details are collected by the form. Reports cannot change facts, permissions or publication pointers. Best-effort edge-IP limit5 reports per60seconds; no automated retries.",
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "https://localfactbook.com"
            }
          },
          {
            "name": "X-LocalFactBook-Request",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "correction"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CorrectionReport"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Report recorded for review; no publication changed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CorrectionReceipt"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "415": {
            "description": "JSON content type is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        }
      }
    },
    "/api/v1/sources/{id}": {
      "get": {
        "operationId": "getsources",
        "summary": "Read one source resource from the current approved publication.",
        "description": "Current release quality and source display rights are checked before returning a resource or304. Unknown and withheld resources both return404. Returned Source.rights is immutable publication-time evidence scoped by publicationId, not current export or commercial authorization. Export/commercial changes alone can leave this historical representation and ETag unchanged. PlaceResponse.effectivePermissions reports current display/export permission for a place snapshot; CSV independently enforces current export permission.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 256
            }
          },
          {
            "name": "If-None-Match",
            "in": "header",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Source resource and publication identity.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceResponse"
                }
              }
            },
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "304": {
            "description": "The currently authorized resource matches the ETag."
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        }
      }
    },
    "/api/v1/source-releases/{id}": {
      "get": {
        "operationId": "getsourcereleases",
        "summary": "Read one source resource from the current approved publication.",
        "description": "Current release quality and source display rights are checked before returning a resource or304. Unknown and withheld resources both return404.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 256
            }
          },
          {
            "name": "If-None-Match",
            "in": "header",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Source resource and publication identity.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceReleaseResponse"
                }
              }
            },
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "304": {
            "description": "The currently authorized resource matches the ETag."
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        }
      }
    },
    "/api/v1/metrics": {
      "get": {
        "operationId": "listmetrics",
        "summary": "Metric definitions, units, denominators, supported geography types and MOE fields.",
        "description": "Only records reachable from the current QA-passed, editorial-approved publication are returned. Optional geography narrows the catalog; observations require it. Cursor order is lexical resource identity. next:null ends the result. Opaque cursors bind the production publication, full eligible inventory/permissions, normalized filters and limit; plain IDs are rejected. Restart on409 publication_changed, inventory_changed or publication_unavailable; changed scope is400. publicationId:null with empty data means there is no production pointer; a retained but withheld publication fails503 on a first page,409 on continuation. This catalog refuses inventories above 5000 snapshots; national-scale catalog indexing remains future work.",
        "parameters": [
          {
            "name": "geography",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_:-]{1,100}$"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "after",
            "in": "query",
            "description": "Opaque next cursor for this unchanged request and limit; maximum2048 characters. Never a record ID or authorization.",
            "schema": {
              "type": "string",
              "maxLength": 2048,
              "pattern": "^[A-Za-z0-9_-]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Metric definitions, units, denominators, supported geography types and MOE fields.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetricListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        }
      }
    },
    "/api/v1/sources": {
      "get": {
        "operationId": "listsources",
        "summary": "Source attribution, documentation and immutable publication-time rights evidence.",
        "description": "Only records reachable from the current QA-passed, editorial-approved publication are returned. Optional geography narrows the catalog; observations require it. Cursor order is lexical resource identity. next:null ends the result. Opaque cursors bind the production publication, full eligible inventory/permissions, normalized filters and limit; plain IDs are rejected. Restart on409 publication_changed, inventory_changed or publication_unavailable; changed scope is400. publicationId:null with empty data means there is no production pointer; a retained but withheld publication fails503 on a first page,409 on continuation. This catalog refuses inventories above 5000 snapshots; national-scale catalog indexing remains future work.",
        "parameters": [
          {
            "name": "geography",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_:-]{1,100}$"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "after",
            "in": "query",
            "description": "Opaque next cursor for this unchanged request and limit; maximum2048 characters. Never a record ID or authorization.",
            "schema": {
              "type": "string",
              "maxLength": 2048,
              "pattern": "^[A-Za-z0-9_-]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Source attribution, documentation and immutable publication-time rights evidence.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        }
      }
    },
    "/api/v1/source-releases": {
      "get": {
        "operationId": "listsourcereleases",
        "summary": "Release periods, retrieval timestamps, raw checksums and parser versions.",
        "description": "Only records reachable from the current QA-passed, editorial-approved publication are returned. Optional geography narrows the catalog; observations require it. Cursor order is lexical resource identity. next:null ends the result. Opaque cursors bind the production publication, full eligible inventory/permissions, normalized filters and limit; plain IDs are rejected. Restart on409 publication_changed, inventory_changed or publication_unavailable; changed scope is400. publicationId:null with empty data means there is no production pointer; a retained but withheld publication fails503 on a first page,409 on continuation. This catalog refuses inventories above 5000 snapshots; national-scale catalog indexing remains future work.",
        "parameters": [
          {
            "name": "geography",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_:-]{1,100}$"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "after",
            "in": "query",
            "description": "Opaque next cursor for this unchanged request and limit; maximum2048 characters. Never a record ID or authorization.",
            "schema": {
              "type": "string",
              "maxLength": 2048,
              "pattern": "^[A-Za-z0-9_-]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Release periods, retrieval timestamps, raw checksums and parser versions.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceReleaseListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        }
      }
    },
    "/api/v1/observations": {
      "get": {
        "operationId": "listobservations",
        "summary": "Native observations with missingness, MOE and provenance; one geography is required.",
        "description": "Only records reachable from the current QA-passed, editorial-approved publication are returned. Optional geography narrows the catalog; observations require it. Cursor order is lexical resource identity. next:null ends the result. Opaque cursors bind the production publication, full eligible inventory/permissions, normalized filters and limit; plain IDs are rejected. Restart on409 publication_changed, inventory_changed or publication_unavailable; changed scope is400. publicationId:null with empty data means there is no production pointer; a retained but withheld publication fails503 on a first page,409 on continuation. This catalog refuses inventories above 5000 snapshots; national-scale catalog indexing remains future work.",
        "parameters": [
          {
            "name": "geography",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_:-]{1,100}$"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "after",
            "in": "query",
            "description": "Opaque next cursor for this unchanged request and limit; maximum2048 characters. Never a record ID or authorization.",
            "schema": {
              "type": "string",
              "maxLength": 2048,
              "pattern": "^[A-Za-z0-9_-]+$"
            }
          },
          {
            "name": "metric",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9_]{0,80}$"
            }
          },
          {
            "name": "periodStart",
            "in": "query",
            "description": "Inclusive earliest observation start.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "periodEnd",
            "in": "query",
            "description": "Inclusive latest observation end.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Native observations with missingness, MOE and provenance; one geography is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ObservationListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        }
      }
    },
    "/api/v1/geographies": {
      "get": {
        "operationId": "listGeographies",
        "summary": "Search approved geography publications",
        "description": "Results are ordered by stable geography id. Pass next as after to continue; next:null ends traversal without an extra empty page. Cursors bind current publication, full eligible inventory/permissions, NFKC-trimmed q and limit. Plain IDs and unknown/repeated parameters are rejected. Restart on409 after publication/inventory changes. An empty match array is valid; an existing withheld publication returns503 initially or409 on continuation. Search q currently matches the published display name, not an unrestricted geocoder.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Display-name search text, trimmed before length validation.",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "after",
            "in": "query",
            "required": false,
            "description": "Opaque next cursor for the unchanged normalized q and limit; publication/inventory changes require restart.",
            "schema": {
              "type": "string",
              "maxLength": 2048,
              "pattern": "^[A-Za-z0-9_-]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Approved geography records and the next cursor.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeographyListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        }
      }
    },
    "/api/v1/places/{id}": {
      "get": {
        "operationId": "getPlace",
        "summary": "Read a source-linked approved place snapshot",
        "description": "The snapshot includes source lineage, reference periods and missing-value states. Embedded source.rights records publication-time evidence. effectivePermissions reflects current display/export authorization. Revalidation occurs before ETag reuse; a rights change changes the permission-sensitive ETag.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Stable geography identity, for example place:1225175. Only approved publication data is returned.",
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_:-]{1,100}$",
              "maxLength": 100
            },
            "example": "place:1225175"
          },
          {
            "name": "If-None-Match",
            "in": "header",
            "required": false,
            "description": "Previously returned ETag. A matching current representation returns 304 after rights checks.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The approved snapshot and current effective permissions.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlaceResponse"
                }
              }
            },
            "headers": {
              "ETag": {
                "description": "Quoted snapshot identity plus effective permission suffix :export or :display.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            }
          },
          "304": {
            "description": "The current authorized representation matches If-None-Match. No response body.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        }
      }
    },
    "/api/v1/places/{id}.csv": {
      "get": {
        "operationId": "exportPlaceCsv",
        "summary": "Download an approved place snapshot when export rights permit",
        "description": "Requires an approved publication and current export permission from every applicable source. Display permission alone is insufficient. CSV preserves geography, metric, status, unit, period, margin of error, source release, source URL and publication id. Spreadsheet-formula text is escaped.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Stable geography identity, for example place:1225175. Only approved publication data is returned.",
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_:-]{1,100}$",
              "maxLength": 100
            },
            "example": "place:1225175"
          }
        ],
        "responses": {
          "200": {
            "description": "UTF-8 source-linked CSV with a header row and CRLF line endings.",
            "headers": {
              "Content-Disposition": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        }
      }
    },
    "/api/v1/compare": {
      "get": {
        "operationId": "comparePlaces",
        "summary": "Compare one metric across two distinct approved geographies",
        "description": "Both observations must belong to one approved publication. The shared comparability resolver checks geography, vintage, periods, definitions, units and missingness. A 200 result can be incompatible, with no numeric difference. Descriptive differences are second place minus first place; statistical significance is not evaluated.",
        "parameters": [
          {
            "name": "ids",
            "in": "query",
            "required": true,
            "style": "form",
            "explode": false,
            "description": "Two distinct geography ids, comma separated.",
            "schema": {
              "type": "array",
              "minItems": 2,
              "maxItems": 2,
              "uniqueItems": true,
              "items": {
                "type": "string",
                "pattern": "^[-\\w:]{1,100}$"
              }
            },
            "example": [
              "place:1225175",
              "place:4805000"
            ]
          },
          {
            "name": "metric",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9_]{0,80}$"
            },
            "example": "population"
          }
        ],
        "responses": {
          "200": {
            "description": "Both source observations, compatibility reasons/caveats and publication identity.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ComparisonResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        }
      }
    },
    "/api/v1/rankings/{rankingId}": {
      "get": {
        "operationId": "getCurrentRanking",
        "summary": "Descriptive ordering within an explicit current approved native-type cohort",
        "description": "rankingId is current-place-{metric} or current-cdp-{metric}. Membership is the entire current approved publication for that native type, not a national/statewide or curated ranking. At least two members and complete compatible metric coverage are required. All members share one publication, source product, release/geography vintage and observation window. Other native types are disclosed as excluded counts. Overlap is not assessed and uncertainty/significance is not calculated. Missing, suppressed, rights-withheld or incompatible selected members withhold the whole ranking. Cursors bind publication, cohort and direction; a changed publication requires restart. Membership is checked before/after reads and current rights are re-read before 304; this is bounded multi-read validation, not global transaction isolation.",
        "parameters": [
          {
            "name": "rankingId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^current-(place|cdp)-[a-z][a-z0-9_]{0,80}$"
            },
            "example": "current-place-population"
          },
          {
            "name": "direction",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ascending",
                "descending"
              ],
              "default": "descending"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "after",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 1024
            },
            "description": "Opaque next cursor from this same ranking and direction."
          },
          {
            "name": "If-None-Match",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "description": "Exact quoted ETag returned for this ranking page."
          }
        ],
        "responses": {
          "200": {
            "description": "Current full-coverage cohort metadata and one bounded page of source observations.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RankingResponse"
                }
              }
            },
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            }
          },
          "304": {
            "description": "No body. Current membership, source rights and exact representation revalidated.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        }
      }
    },
    "/api/v1/geographies/suggestions": {
      "get": {
        "operationId": "suggestGeographies",
        "summary": "Bounded deterministic suggestions from current approved geography publications.",
        "description": "At most8 current eligible place/CDP identities; exact native state/type qualifiers are resolved before matching. Full scoped ambiguity is retained in response headers even at limit1. Exact IDs/names outrank prefix/token and conservative one-edit spelling candidates. Selection is always explicit; no alias, ZIP equivalence, centroid, parent or dataset coverage is inferred. Empty q returns empty without browsing. Strict duplicate/unknown/control-character rejection. Entire inventory must be coherent and at most 5000; source rights and QA apply on every no-store request. Preview fallback is a separately labeled website feature, never API data. next is always null.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 8,
              "default": 8
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "place",
                "cdp"
              ]
            }
          },
          {
            "name": "stateFips",
            "in": "query",
            "description": "One actual50-state/DC FIPS code; unsupported codes rejected.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{2}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bounded current-publication matches. Selection metadata includes matching eligible identities hidden by the result limit; the JSON list contract and next:null remain unchanged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeographyListResponse"
                }
              }
            },
            "headers": {
              "X-Geography-Matches": {
                "description": "Total matches inside the current authorized inventory only, never the private national registry.",
                "schema": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 16000
                }
              },
              "X-Geography-Selection": {
                "description": "A truncated or spelling-only result still requires explicit choice.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "not_found",
                    "single_match",
                    "requires_explicit_choice"
                  ]
                }
              },
              "X-Geography-Truncated": {
                "description": "True when matching identities exceed returned rows.",
                "schema": {
                  "type": "boolean"
                }
              },
              "X-Geography-As-Of": {
                "description": "UTC eligibility date used to evaluate native geography validity.",
                "schema": {
                  "type": "string",
                  "format": "date"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        }
      }
    },
    "/healthz": {
      "get": {
        "operationId": "healthCheck",
        "summary": "Check publication-service database connectivity",
        "description": "Executes a lightweight database connectivity query. An ok response proves connectivity for this request; it does not prove a populated publication, source freshness or search-engine indexing.",
        "responses": {
          "200": {
            "description": "Database connectivity is available.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "GeographyType": {
        "type": "string",
        "enum": [
          "us",
          "state",
          "county",
          "place",
          "cdp",
          "cbsa",
          "zcta",
          "postal_zip",
          "tract",
          "block_group",
          "school_district"
        ]
      },
      "RightsState": {
        "type": "string",
        "enum": [
          "review_required",
          "approved",
          "restricted",
          "withdrawn"
        ]
      },
      "Geography": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "type": {
            "$ref": "#/components/schemas/GeographyType"
          },
          "geoid": {
            "type": "string",
            "minLength": 1
          },
          "displayName": {
            "type": "string",
            "minLength": 1
          },
          "stateFips": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^\\d{2}$"
            },
            "uniqueItems": true
          },
          "vintage": {
            "type": "string",
            "minLength": 1
          },
          "validFrom": {
            "type": "string",
            "format": "date"
          },
          "validTo": {
            "anyOf": [
              {
                "type": "string",
                "format": "date"
              },
              {
                "type": "null"
              }
            ]
          },
          "canonicalPath": {
            "type": "string",
            "pattern": "^/(?:[a-z0-9-]+(?:/[a-z0-9-]+)*)?$"
          },
          "parentIds": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 256
            },
            "uniqueItems": true
          }
        },
        "required": [
          "id",
          "type",
          "geoid",
          "displayName",
          "stateFips",
          "vintage",
          "validFrom",
          "canonicalPath",
          "parentIds"
        ],
        "additionalProperties": false
      },
      "SourceRights": {
        "type": "object",
        "properties": {
          "display": {
            "$ref": "#/components/schemas/RightsState"
          },
          "export": {
            "$ref": "#/components/schemas/RightsState"
          },
          "commercial": {
            "$ref": "#/components/schemas/RightsState"
          },
          "reviewedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "reviewedBy": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1
              },
              {
                "type": "null"
              }
            ]
          },
          "evidenceUrls": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri",
              "pattern": "^https://[^/?#@]+(?:[/?#]|$)"
            }
          },
          "notes": {
            "type": "string"
          }
        },
        "required": [
          "display",
          "export",
          "commercial",
          "evidenceUrls"
        ],
        "additionalProperties": false
      },
      "Source": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "owner": {
            "type": "string",
            "minLength": 1
          },
          "product": {
            "type": "string",
            "minLength": 1
          },
          "documentationUrl": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://[^/?#@]+(?:[/?#]|$)"
          },
          "endpointUrl": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://[^/?#@]+(?:[/?#]|$)"
          },
          "termsUrl": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://[^/?#@]+(?:[/?#]|$)"
          },
          "attribution": {
            "type": "string",
            "minLength": 1
          },
          "nativeGeographyTypes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GeographyType"
            },
            "minItems": 1
          },
          "rights": {
            "$ref": "#/components/schemas/SourceRights"
          },
          "cadence": {
            "type": "string",
            "minLength": 1
          },
          "expectedLagDays": {
            "type": "integer",
            "minimum": 0
          },
          "nextSyncAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "retentionNotes": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "owner",
          "product",
          "documentationUrl",
          "endpointUrl",
          "termsUrl",
          "attribution",
          "nativeGeographyTypes",
          "rights"
        ],
        "additionalProperties": false
      },
      "SourceRelease": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "sourceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "vintage": {
            "type": "string",
            "minLength": 1
          },
          "periodStart": {
            "type": "string",
            "format": "date"
          },
          "periodEnd": {
            "type": "string",
            "format": "date"
          },
          "releasedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "retrievedAt": {
            "type": "string",
            "format": "date-time"
          },
          "checksum": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "rawObjectKey": {
            "type": "string",
            "minLength": 1
          },
          "parserVersion": {
            "type": "string",
            "minLength": 1
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "validated",
              "quarantined",
              "withdrawn"
            ]
          },
          "notes": {
            "type": "string"
          },
          "releaseDatePrecision": {
            "type": "string",
            "enum": [
              "instant",
              "day",
              "month",
              "year",
              "unknown"
            ]
          },
          "sourceReleaseDate": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 10
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "sourceId",
          "vintage",
          "periodStart",
          "periodEnd",
          "releasedAt",
          "retrievedAt",
          "checksum",
          "rawObjectKey",
          "parserVersion",
          "status"
        ],
        "additionalProperties": false,
        "allOf": [
          {
            "anyOf": [
              {
                "properties": {
                  "releasedAt": {
                    "type": "string"
                  },
                  "releaseDatePrecision": {
                    "const": "instant"
                  },
                  "sourceReleaseDate": {
                    "type": "null"
                  }
                }
              },
              {
                "required": [
                  "releaseDatePrecision",
                  "sourceReleaseDate"
                ],
                "properties": {
                  "releasedAt": {
                    "type": "null"
                  },
                  "releaseDatePrecision": {
                    "const": "day"
                  },
                  "sourceReleaseDate": {
                    "type": "string",
                    "format": "date",
                    "pattern": "^(?!0000)"
                  }
                }
              },
              {
                "required": [
                  "releaseDatePrecision",
                  "sourceReleaseDate"
                ],
                "properties": {
                  "releasedAt": {
                    "type": "null"
                  },
                  "releaseDatePrecision": {
                    "const": "month"
                  },
                  "sourceReleaseDate": {
                    "type": "string",
                    "pattern": "^(?!0000)[0-9]{4}-(0[1-9]|1[0-2])$"
                  }
                }
              },
              {
                "required": [
                  "releaseDatePrecision",
                  "sourceReleaseDate"
                ],
                "properties": {
                  "releasedAt": {
                    "type": "null"
                  },
                  "releaseDatePrecision": {
                    "const": "year"
                  },
                  "sourceReleaseDate": {
                    "type": "string",
                    "pattern": "^(?!0000)[0-9]{4}$"
                  }
                }
              },
              {
                "required": [
                  "releaseDatePrecision",
                  "sourceReleaseDate"
                ],
                "properties": {
                  "releasedAt": {
                    "type": "null"
                  },
                  "releaseDatePrecision": {
                    "const": "unknown"
                  },
                  "sourceReleaseDate": {
                    "type": "null"
                  }
                }
              }
            ]
          }
        ],
        "dependentRequired": {
          "sourceReleaseDate": [
            "releaseDatePrecision"
          ]
        }
      },
      "Metric": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]*$"
          },
          "label": {
            "type": "string",
            "minLength": 1
          },
          "definition": {
            "type": "string",
            "minLength": 1
          },
          "unit": {
            "type": "string",
            "minLength": 1
          },
          "denominator": {
            "type": "string",
            "minLength": 1
          },
          "aggregation": {
            "type": "string",
            "enum": [
              "sum",
              "mean",
              "median",
              "rate",
              "ratio",
              "none"
            ]
          },
          "allowedGeographyTypes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GeographyType"
            },
            "minItems": 1
          },
          "preferredSourceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "displayPrecision": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10
          },
          "methodology": {
            "type": "string",
            "minLength": 1
          },
          "polarity": {
            "type": "string",
            "enum": [
              "higher",
              "lower",
              "neutral"
            ]
          },
          "marginOfErrorField": {
            "type": "string",
            "minLength": 1
          },
          "minimumValue": {
            "type": "number"
          },
          "maximumValue": {
            "type": "number"
          }
        },
        "required": [
          "id",
          "label",
          "definition",
          "unit",
          "denominator",
          "aggregation",
          "allowedGeographyTypes",
          "preferredSourceId",
          "displayPrecision",
          "methodology"
        ],
        "additionalProperties": false
      },
      "ObservationProvenance": {
        "type": "object",
        "properties": {
          "rawObjectKey": {
            "type": "string",
            "minLength": 1
          },
          "sourceUrl": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://[^/?#@]+(?:[/?#]|$)"
          },
          "tableCode": {
            "type": "string",
            "minLength": 1
          },
          "columnCode": {
            "type": "string",
            "minLength": 1
          },
          "transformationDigest": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          }
        },
        "required": [
          "rawObjectKey",
          "sourceUrl",
          "tableCode",
          "columnCode",
          "transformationDigest"
        ],
        "additionalProperties": false
      },
      "CurrencyBasis": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "nominal",
              "real"
            ]
          },
          "baseYear": {
            "type": "integer"
          },
          "adjustmentSeries": {
            "type": "string",
            "minLength": 1
          }
        },
        "required": [
          "kind"
        ],
        "additionalProperties": false,
        "if": {
          "properties": {
            "kind": {
              "const": "real"
            }
          },
          "required": [
            "kind"
          ]
        },
        "then": {
          "required": [
            "baseYear",
            "adjustmentSeries"
          ],
          "properties": {
            "baseYear": {
              "type": "integer"
            },
            "adjustmentSeries": {
              "type": "string",
              "minLength": 1
            }
          }
        }
      },
      "NumericObservation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "geographyId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "geographyType": {
            "$ref": "#/components/schemas/GeographyType"
          },
          "geographyVintage": {
            "type": "string",
            "minLength": 1
          },
          "metricId": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]*$"
          },
          "periodStart": {
            "type": "string",
            "format": "date"
          },
          "periodEnd": {
            "type": "string",
            "format": "date"
          },
          "sourceReleaseId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "value": {
            "type": "number"
          },
          "status": {
            "type": "string",
            "enum": [
              "reported",
              "estimated",
              "provisional",
              "revised"
            ]
          },
          "unit": {
            "type": "string",
            "minLength": 1
          },
          "denominator": {
            "type": "string",
            "minLength": 1
          },
          "methodology": {
            "type": "string",
            "minLength": 1
          },
          "seasonalAdjustment": {
            "type": "string",
            "enum": [
              "none",
              "adjusted",
              "unadjusted"
            ]
          },
          "marginOfError": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0
              },
              {
                "type": "null"
              }
            ]
          },
          "confidenceLevel": {
            "anyOf": [
              {
                "type": "number",
                "exclusiveMinimum": 0,
                "exclusiveMaximum": 1
              },
              {
                "type": "null"
              }
            ]
          },
          "sourcePrecision": {
            "type": "integer",
            "minimum": 0
          },
          "transformationVersion": {
            "type": "string",
            "minLength": 1
          },
          "provenance": {
            "$ref": "#/components/schemas/ObservationProvenance"
          },
          "currencyBasis": {
            "$ref": "#/components/schemas/CurrencyBasis"
          }
        },
        "required": [
          "id",
          "geographyId",
          "geographyType",
          "geographyVintage",
          "metricId",
          "periodStart",
          "periodEnd",
          "sourceReleaseId",
          "value",
          "status",
          "unit",
          "denominator",
          "methodology",
          "seasonalAdjustment",
          "transformationVersion",
          "provenance"
        ],
        "additionalProperties": false
      },
      "MissingObservation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "geographyId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "geographyType": {
            "$ref": "#/components/schemas/GeographyType"
          },
          "geographyVintage": {
            "type": "string",
            "minLength": 1
          },
          "metricId": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]*$"
          },
          "periodStart": {
            "type": "string",
            "format": "date"
          },
          "periodEnd": {
            "type": "string",
            "format": "date"
          },
          "sourceReleaseId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "value": {
            "type": "null"
          },
          "status": {
            "type": "string",
            "enum": [
              "suppressed",
              "unavailable",
              "not_applicable"
            ]
          },
          "unit": {
            "type": "string",
            "minLength": 1
          },
          "denominator": {
            "type": "string",
            "minLength": 1
          },
          "methodology": {
            "type": "string",
            "minLength": 1
          },
          "seasonalAdjustment": {
            "type": "string",
            "enum": [
              "none",
              "adjusted",
              "unadjusted"
            ]
          },
          "marginOfError": {
            "type": "null"
          },
          "confidenceLevel": {
            "anyOf": [
              {
                "type": "number",
                "exclusiveMinimum": 0,
                "exclusiveMaximum": 1
              },
              {
                "type": "null"
              }
            ]
          },
          "sourcePrecision": {
            "type": "integer",
            "minimum": 0
          },
          "transformationVersion": {
            "type": "string",
            "minLength": 1
          },
          "provenance": {
            "$ref": "#/components/schemas/ObservationProvenance"
          },
          "currencyBasis": {
            "$ref": "#/components/schemas/CurrencyBasis"
          },
          "valueInterval": {
            "$ref": "#/components/schemas/ObservationValueInterval"
          }
        },
        "required": [
          "id",
          "geographyId",
          "geographyType",
          "geographyVintage",
          "metricId",
          "periodStart",
          "periodEnd",
          "sourceReleaseId",
          "value",
          "status",
          "unit",
          "denominator",
          "methodology",
          "seasonalAdjustment",
          "transformationVersion",
          "provenance"
        ],
        "additionalProperties": false,
        "allOf": [
          {
            "if": {
              "required": [
                "valueInterval"
              ],
              "properties": {
                "valueInterval": {}
              }
            },
            "then": {
              "properties": {
                "status": {
                  "const": "unavailable"
                },
                "value": {
                  "type": "null"
                },
                "marginOfError": {
                  "type": "null"
                },
                "confidenceLevel": {
                  "type": "null"
                }
              },
              "required": [
                "marginOfError",
                "confidenceLevel"
              ]
            }
          }
        ]
      },
      "Observation": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/NumericObservation"
          },
          {
            "$ref": "#/components/schemas/MissingObservation"
          }
        ]
      },
      "ReviewDecision": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "reviewer": {
            "type": "string",
            "minLength": 1
          },
          "reviewedAt": {
            "type": "string",
            "format": "date-time"
          },
          "outcome": {
            "type": "string",
            "enum": [
              "approved",
              "rejected",
              "review_required"
            ]
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "id",
          "reviewer",
          "reviewedAt",
          "outcome",
          "reasons"
        ],
        "additionalProperties": false
      },
      "Snapshot": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "publicationId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "geography": {
            "$ref": "#/components/schemas/Geography"
          },
          "observations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Observation"
            }
          },
          "metrics": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Metric"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Source"
            }
          },
          "sourceReleases": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SourceRelease"
            }
          },
          "templateVersion": {
            "type": "string",
            "minLength": 1
          },
          "methodVersion": {
            "type": "string",
            "minLength": 1
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "lastMaterialChangeAt": {
            "type": "string",
            "format": "date-time"
          },
          "review": {
            "$ref": "#/components/schemas/ReviewDecision"
          },
          "demo": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "publicationId",
          "geography",
          "observations",
          "metrics",
          "sources",
          "sourceReleases",
          "templateVersion",
          "methodVersion",
          "generatedAt",
          "lastMaterialChangeAt",
          "review"
        ],
        "additionalProperties": false
      },
      "ComparisonResult": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "compatible",
                  "compatible_with_caveat"
                ]
              },
              "reasons": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "maxItems": 0
              },
              "caveats": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "difference": {
                "type": "number"
              },
              "percentageDifference": {
                "anyOf": [
                  {
                    "type": "number"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "significance": {
                "const": "not_evaluated"
              },
              "observationIds": {
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 256
                },
                "minItems": 2,
                "maxItems": 2
              }
            },
            "required": [
              "status",
              "reasons",
              "caveats",
              "difference",
              "percentageDifference",
              "significance",
              "observationIds"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "status": {
                "const": "incompatible"
              },
              "reasons": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "minItems": 1
              },
              "caveats": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "difference": {
                "type": "null"
              },
              "percentageDifference": {
                "type": "null"
              },
              "significance": {
                "const": "not_evaluated"
              },
              "observationIds": {
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 256
                },
                "minItems": 2,
                "maxItems": 2
              }
            },
            "required": [
              "status",
              "reasons",
              "caveats",
              "difference",
              "percentageDifference",
              "significance",
              "observationIds"
            ],
            "additionalProperties": false
          }
        ]
      },
      "GeographySummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "type": {
            "$ref": "#/components/schemas/GeographyType"
          },
          "geoid": {
            "type": "string",
            "minLength": 1
          },
          "displayName": {
            "type": "string",
            "minLength": 1
          },
          "stateFips": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^\\d{2}$"
            },
            "uniqueItems": true
          },
          "vintage": {
            "type": "string",
            "minLength": 1
          },
          "validFrom": {
            "type": "string",
            "format": "date"
          },
          "validTo": {
            "anyOf": [
              {
                "type": "string",
                "format": "date"
              },
              {
                "type": "null"
              }
            ]
          },
          "canonicalPath": {
            "type": "string",
            "pattern": "^/(?:[a-z0-9-]+(?:/[a-z0-9-]+)*)?$"
          },
          "parentIds": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 256
            },
            "uniqueItems": true
          },
          "canonicalUrl": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://[^/?#@]+(?:[/?#]|$)"
          },
          "publicationId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "supportedDatasets": {
            "type": "array",
            "maxItems": 1000,
            "items": {
              "$ref": "#/components/schemas/SupportedGeographyDataset"
            }
          }
        },
        "required": [
          "id",
          "type",
          "geoid",
          "displayName",
          "stateFips",
          "vintage",
          "validFrom",
          "canonicalPath",
          "parentIds",
          "canonicalUrl",
          "publicationId"
        ],
        "additionalProperties": false
      },
      "GeographyListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GeographySummary"
            },
            "maxItems": 50
          },
          "next": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ListCursor"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "data",
          "next"
        ],
        "additionalProperties": false
      },
      "PlaceResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Snapshot"
          },
          "canonicalUrl": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://[^/?#@]+(?:[/?#]|$)"
          },
          "effectivePermissions": {
            "type": "object",
            "properties": {
              "display": {
                "const": true
              },
              "export": {
                "type": "boolean"
              }
            },
            "required": [
              "display",
              "export"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "data",
          "canonicalUrl",
          "effectivePermissions"
        ],
        "additionalProperties": false
      },
      "ComparisonResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "left": {
                "$ref": "#/components/schemas/Observation"
              },
              "right": {
                "$ref": "#/components/schemas/Observation"
              },
              "compatibility": {
                "$ref": "#/components/schemas/ComparisonResult"
              },
              "publicationId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 256
              }
            },
            "required": [
              "left",
              "right",
              "compatibility",
              "publicationId"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "data"
        ],
        "additionalProperties": false
      },
      "ApiError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "pattern": "^[a-z][a-z0-9_]*$"
              },
              "message": {
                "type": "string",
                "minLength": 1
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "status": {
            "const": "ok"
          },
          "service": {
            "const": "localfactbook"
          },
          "version": {
            "type": "string",
            "minLength": 1
          }
        },
        "required": [
          "status",
          "service",
          "version"
        ],
        "additionalProperties": false
      },
      "CsvObservation": {
        "type": "object",
        "properties": {
          "geography_id": {
            "type": "string",
            "minLength": 1
          },
          "geography_name": {
            "type": "string",
            "minLength": 1
          },
          "geography_vintage": {
            "type": "string",
            "minLength": 1
          },
          "metric_id": {
            "type": "string",
            "minLength": 1
          },
          "value": {
            "type": "string"
          },
          "unit": {
            "type": "string",
            "minLength": 1
          },
          "status": {
            "type": "string",
            "enum": [
              "reported",
              "estimated",
              "provisional",
              "revised",
              "suppressed",
              "unavailable",
              "not_applicable"
            ]
          },
          "period_start": {
            "type": "string",
            "format": "date"
          },
          "period_end": {
            "type": "string",
            "format": "date"
          },
          "margin_of_error": {
            "type": "string"
          },
          "source_release_id": {
            "type": "string",
            "minLength": 1
          },
          "source_url": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://[^/?#@]+(?:[/?#]|$)"
          },
          "publication_id": {
            "type": "string",
            "minLength": 1
          }
        },
        "required": [
          "geography_id",
          "geography_name",
          "geography_vintage",
          "metric_id",
          "value",
          "unit",
          "status",
          "period_start",
          "period_end",
          "margin_of_error",
          "source_release_id",
          "source_url",
          "publication_id"
        ],
        "additionalProperties": false
      },
      "GoldenObservation": {
        "type": "object",
        "properties": {
          "geographyId": {
            "type": "string",
            "minLength": 1
          },
          "geographyVintage": {
            "type": "string",
            "minLength": 1
          },
          "metricId": {
            "type": "string",
            "minLength": 1
          },
          "periodStart": {
            "type": "string",
            "format": "date"
          },
          "periodEnd": {
            "type": "string",
            "format": "date"
          },
          "expectedValue": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "expectedStatus": {
            "type": "string",
            "enum": [
              "reported",
              "estimated",
              "provisional",
              "revised",
              "suppressed",
              "unavailable",
              "not_applicable"
            ]
          },
          "unit": {
            "type": "string",
            "minLength": 1
          },
          "tolerance": {
            "type": "number",
            "minimum": 0
          },
          "sourceEvidenceUrl": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://[^/?#@]+(?:[/?#]|$)"
          }
        },
        "required": [
          "geographyId",
          "geographyVintage",
          "metricId",
          "periodStart",
          "periodEnd",
          "expectedValue",
          "expectedStatus",
          "unit",
          "tolerance",
          "sourceEvidenceUrl"
        ],
        "additionalProperties": false
      },
      "ReconciliationRule": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1
          },
          "metricId": {
            "type": "string",
            "minLength": 1
          },
          "geographyIds": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            },
            "minItems": 1,
            "uniqueItems": true
          },
          "geographyVintage": {
            "type": "string",
            "minLength": 1
          },
          "periodStart": {
            "type": "string",
            "format": "date"
          },
          "periodEnd": {
            "type": "string",
            "format": "date"
          },
          "expectedTotal": {
            "type": "number"
          },
          "absoluteTolerance": {
            "type": "number",
            "minimum": 0
          },
          "nonOverlappingPartition": {
            "type": "boolean"
          },
          "evidenceUrl": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://[^/?#@]+(?:[/?#]|$)"
          }
        },
        "required": [
          "id",
          "metricId",
          "geographyIds",
          "geographyVintage",
          "periodStart",
          "periodEnd",
          "expectedTotal",
          "absoluteTolerance",
          "nonOverlappingPartition",
          "evidenceUrl"
        ],
        "additionalProperties": false
      },
      "ComponentReconciliationRule": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1
          },
          "geographyId": {
            "type": "string",
            "minLength": 1
          },
          "geographyVintage": {
            "type": "string",
            "minLength": 1
          },
          "periodStart": {
            "type": "string",
            "format": "date"
          },
          "periodEnd": {
            "type": "string",
            "format": "date"
          },
          "totalMetricId": {
            "type": "string",
            "minLength": 1
          },
          "componentMetricIds": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            },
            "minItems": 1,
            "uniqueItems": true
          },
          "absoluteTolerance": {
            "type": "number",
            "minimum": 0
          },
          "evidenceUrl": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://[^/?#@]+(?:[/?#]|$)"
          }
        },
        "required": [
          "id",
          "geographyId",
          "geographyVintage",
          "periodStart",
          "periodEnd",
          "totalMetricId",
          "componentMetricIds",
          "absoluteTolerance",
          "evidenceUrl"
        ],
        "additionalProperties": false
      },
      "MetricSourceRule": {
        "type": "object",
        "properties": {
          "metricId": {
            "type": "string",
            "minLength": 1
          },
          "allowedSourceIds": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            },
            "minItems": 1,
            "uniqueItems": true
          }
        },
        "required": [
          "metricId",
          "allowedSourceIds"
        ],
        "additionalProperties": false
      },
      "QualityPolicy": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1
          },
          "version": {
            "type": "string",
            "minLength": 1
          },
          "asOf": {
            "type": "string",
            "format": "date"
          },
          "expectedGeographyIds": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            },
            "minItems": 1,
            "uniqueItems": true
          },
          "requiredMetricIds": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            },
            "minItems": 1,
            "uniqueItems": true
          },
          "requiredMetricIdsByGeographyType": {
            "type": "object",
            "propertyNames": {
              "enum": [
                "us",
                "state",
                "county",
                "place",
                "cdp",
                "cbsa",
                "zcta",
                "postal_zip",
                "tract",
                "block_group",
                "school_district"
              ]
            },
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              },
              "minItems": 1,
              "uniqueItems": true
            }
          },
          "maximumNullFraction": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "maximumNullFractionIncrease": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "maximumRowLossFraction": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "minimumGeographyCoverage": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "maximumObservationPeriodEnd": {
            "type": "string",
            "format": "date"
          },
          "minimumObservationPeriodEnd": {
            "type": "string",
            "format": "date"
          },
          "metricSourceRules": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MetricSourceRule"
            }
          },
          "componentReconciliations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ComponentReconciliationRule"
            }
          },
          "goldenObservations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GoldenObservation"
            }
          },
          "reconciliations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReconciliationRule"
            }
          }
        },
        "required": [
          "id",
          "version",
          "asOf",
          "expectedGeographyIds",
          "requiredMetricIds",
          "maximumNullFraction",
          "maximumNullFractionIncrease",
          "maximumRowLossFraction",
          "minimumGeographyCoverage"
        ],
        "additionalProperties": false
      },
      "ValidationIssue": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "minLength": 1
          },
          "field": {
            "type": "string",
            "minLength": 1
          },
          "message": {
            "type": "string",
            "minLength": 1
          },
          "severity": {
            "type": "string",
            "enum": [
              "critical",
              "warning"
            ]
          },
          "entityId": {
            "type": "string",
            "minLength": 1
          }
        },
        "required": [
          "code",
          "field",
          "message",
          "severity"
        ],
        "additionalProperties": false
      },
      "QualityAssessment": {
        "type": "object",
        "properties": {
          "policyId": {
            "type": "string",
            "minLength": 1
          },
          "policyVersion": {
            "type": "string",
            "minLength": 1
          },
          "approved": {
            "type": "boolean"
          },
          "issues": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ValidationIssue"
            }
          },
          "counts": {
            "type": "object",
            "properties": {
              "rows": {
                "type": "integer",
                "minimum": 0
              },
              "previousRows": {
                "type": "integer",
                "minimum": 0
              },
              "missingRows": {
                "type": "integer",
                "minimum": 0
              },
              "expectedGeographies": {
                "type": "integer",
                "minimum": 0
              },
              "coveredGeographies": {
                "type": "integer",
                "minimum": 0
              }
            },
            "required": [
              "rows",
              "previousRows",
              "missingRows",
              "expectedGeographies",
              "coveredGeographies"
            ],
            "additionalProperties": false
          },
          "nullFraction": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "previousNullFraction": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              {
                "type": "null"
              }
            ]
          },
          "rowLossFraction": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "geographyCoverage": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "checkedObservationIds": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            },
            "uniqueItems": true
          },
          "actionableAlert": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "severity": {
                    "const": "critical"
                  },
                  "codes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1
                    }
                  },
                  "affectedEntityIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1
                    }
                  },
                  "message": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "required": [
                  "severity",
                  "codes",
                  "affectedEntityIds",
                  "message"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "policyId",
          "policyVersion",
          "approved",
          "issues",
          "counts",
          "nullFraction",
          "previousNullFraction",
          "rowLossFraction",
          "geographyCoverage",
          "checkedObservationIds",
          "actionableAlert"
        ],
        "additionalProperties": false
      },
      "PublicationQualityEvidence": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1
          },
          "status": {
            "type": "string",
            "enum": [
              "missing",
              "passed",
              "failed"
            ]
          },
          "environment": {
            "type": "string",
            "enum": [
              "production",
              "staging"
            ]
          },
          "publicationId": {
            "type": "string",
            "minLength": 1
          },
          "policy": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/QualityPolicy"
              },
              {
                "type": "null"
              }
            ]
          },
          "policyChecksum": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              {
                "type": "null"
              }
            ]
          },
          "inputChecksum": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "snapshotChecksums": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "snapshotId": {
                  "type": "string",
                  "minLength": 1
                },
                "checksum": {
                  "type": "string",
                  "pattern": "^[a-f0-9]{64}$"
                }
              },
              "required": [
                "snapshotId",
                "checksum"
              ],
              "additionalProperties": false
            },
            "minItems": 1
          },
          "actionableAlert": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "severity": {
                    "const": "critical"
                  },
                  "codes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1
                    }
                  },
                  "publicationId": {
                    "type": "string",
                    "minLength": 1
                  },
                  "message": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "required": [
                  "severity",
                  "codes",
                  "publicationId",
                  "message"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "baseline": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "publicationId": {
                    "anyOf": [
                      {
                        "type": "string",
                        "minLength": 1
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "reason": {
                    "type": "string",
                    "minLength": 10
                  }
                },
                "required": [
                  "publicationId",
                  "reason"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "resolvedBaselinePublicationId": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1
              },
              {
                "type": "null"
              }
            ]
          },
          "baselineSnapshotChecksums": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          "assessment": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/QualityAssessment"
              },
              {
                "type": "null"
              }
            ]
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          },
          "assessedBy": {
            "type": "string",
            "minLength": 1
          }
        },
        "required": [
          "id",
          "status",
          "environment",
          "publicationId",
          "policy",
          "policyChecksum",
          "inputChecksum",
          "snapshotChecksums",
          "actionableAlert",
          "baseline",
          "resolvedBaselinePublicationId",
          "baselineSnapshotChecksums",
          "assessment",
          "reasons",
          "assessedBy"
        ],
        "additionalProperties": false
      },
      "MetricListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Metric"
            },
            "maxItems": 50
          },
          "next": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ListCursor"
              },
              {
                "type": "null"
              }
            ]
          },
          "publicationId": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 256
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "data",
          "next",
          "publicationId"
        ],
        "additionalProperties": false
      },
      "SourceListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Source"
            },
            "maxItems": 50
          },
          "next": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ListCursor"
              },
              {
                "type": "null"
              }
            ]
          },
          "publicationId": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 256
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "data",
          "next",
          "publicationId"
        ],
        "additionalProperties": false
      },
      "SourceReleaseListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SourceRelease"
            },
            "maxItems": 50
          },
          "next": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ListCursor"
              },
              {
                "type": "null"
              }
            ]
          },
          "publicationId": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 256
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "data",
          "next",
          "publicationId"
        ],
        "additionalProperties": false
      },
      "ObservationListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Observation"
            },
            "maxItems": 50
          },
          "next": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ListCursor"
              },
              {
                "type": "null"
              }
            ]
          },
          "publicationId": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 256
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "data",
          "next",
          "publicationId"
        ],
        "additionalProperties": false
      },
      "SourceResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Source"
          },
          "publicationId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          }
        },
        "required": [
          "data",
          "publicationId"
        ],
        "additionalProperties": false
      },
      "SourceReleaseResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/SourceRelease"
          },
          "publicationId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          }
        },
        "required": [
          "data",
          "publicationId"
        ],
        "additionalProperties": false
      },
      "CorrectionReport": {
        "type": "object",
        "properties": {
          "geographyId": {
            "type": "string",
            "pattern": "^[-\\w:]{1,100}$"
          },
          "metricId": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]{0,80}$"
          },
          "sourceUrl": {
            "type": "string",
            "format": "uri",
            "maxLength": 2000
          },
          "reportedIssue": {
            "type": "string",
            "minLength": 20,
            "maxLength": 4000
          }
        },
        "required": [
          "geographyId",
          "metricId",
          "sourceUrl",
          "reportedIssue"
        ],
        "additionalProperties": false
      },
      "CorrectionReceipt": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^correction:[a-f0-9-]{36}$"
              },
              "state": {
                "const": "received"
              },
              "reportedAt": {
                "type": "string",
                "format": "date-time"
              },
              "message": {
                "type": "string",
                "maxLength": 512
              }
            },
            "required": [
              "id",
              "state",
              "reportedAt",
              "message"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "data"
        ],
        "additionalProperties": false
      },
      "PublicCorrection": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "geographyId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "metricId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 81
          },
          "geographyName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "metricLabel": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "canonicalUrl": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2048,
            "format": "uri"
          },
          "resolution": {
            "type": "string",
            "minLength": 1,
            "maxLength": 10000
          },
          "resolvedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "geographyId",
          "metricId",
          "geographyName",
          "metricLabel",
          "canonicalUrl",
          "resolution",
          "resolvedAt"
        ],
        "additionalProperties": false
      },
      "CorrectionHistoryResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicCorrection"
            },
            "maxItems": 50
          },
          "next": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ListCursor"
              },
              {
                "type": "null"
              }
            ]
          },
          "publicationId": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 256
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "data",
          "next",
          "publicationId"
        ],
        "additionalProperties": false
      },
      "RankingEntry": {
        "type": "object",
        "properties": {
          "rank": {
            "type": "integer",
            "minimum": 1,
            "maximum": 16000
          },
          "geographyId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "geographyName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "canonicalUrl": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://[^/?#@]+(?:[/?#]|$)"
          },
          "snapshotId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "observation": {
            "$ref": "#/components/schemas/NumericObservation"
          }
        },
        "required": [
          "rank",
          "geographyId",
          "geographyName",
          "canonicalUrl",
          "snapshotId",
          "observation"
        ],
        "additionalProperties": false
      },
      "RankingExcludedType": {
        "type": "object",
        "properties": {
          "geographyType": {
            "$ref": "#/components/schemas/GeographyType"
          },
          "count": {
            "type": "integer",
            "minimum": 1,
            "maximum": 16000
          }
        },
        "required": [
          "geographyType",
          "count"
        ],
        "additionalProperties": false
      },
      "CurrentRanking": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^current-(place|cdp)-[a-z][a-z0-9_]{0,80}$"
          },
          "publicationId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "scope": {
            "const": "current_approved_publication"
          },
          "curated": {
            "const": false
          },
          "geographyType": {
            "enum": [
              "place",
              "cdp"
            ]
          },
          "geographyVintage": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "sourceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "sourceVintage": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "sourceReleaseIds": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 256
            },
            "minItems": 1,
            "maxItems": 1000,
            "uniqueItems": true
          },
          "metric": {
            "$ref": "#/components/schemas/Metric"
          },
          "periodStart": {
            "type": "string",
            "format": "date"
          },
          "periodEnd": {
            "type": "string",
            "format": "date"
          },
          "direction": {
            "enum": [
              "ascending",
              "descending"
            ]
          },
          "tiePolicy": {
            "const": "competition"
          },
          "eligibleCount": {
            "type": "integer",
            "minimum": 2,
            "maximum": 16000
          },
          "universeCount": {
            "type": "integer",
            "minimum": 2,
            "maximum": 16000
          },
          "coverage": {
            "const": 1
          },
          "publicationGeographyCount": {
            "type": "integer",
            "minimum": 2,
            "maximum": 16000
          },
          "excludedOtherNativeGeographyCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 16000
          },
          "excludedByType": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RankingExcludedType"
            },
            "minItems": 0,
            "maxItems": 11
          },
          "overlap": {
            "type": "object",
            "properties": {
              "status": {
                "const": "unknown"
              },
              "policy": {
                "const": "included_with_warning"
              }
            },
            "required": [
              "status",
              "policy"
            ],
            "additionalProperties": false
          },
          "significance": {
            "const": "not_evaluated"
          },
          "warnings": {
            "type": "array",
            "items": {
              "enum": [
                "overlap_not_assessed",
                "descriptive_current_publication_cohort_not_national_or_statewide",
                "uncertainty_not_propagated_no_significance_claim"
              ]
            },
            "minItems": 3,
            "maxItems": 3,
            "uniqueItems": true
          },
          "entries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RankingEntry"
            },
            "minItems": 1,
            "maxItems": 50
          }
        },
        "required": [
          "id",
          "publicationId",
          "scope",
          "curated",
          "geographyType",
          "geographyVintage",
          "sourceId",
          "sourceVintage",
          "sourceReleaseIds",
          "metric",
          "periodStart",
          "periodEnd",
          "direction",
          "tiePolicy",
          "eligibleCount",
          "universeCount",
          "coverage",
          "publicationGeographyCount",
          "excludedOtherNativeGeographyCount",
          "excludedByType",
          "overlap",
          "significance",
          "warnings",
          "entries"
        ],
        "additionalProperties": false
      },
      "RankingResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/CurrentRanking"
          },
          "next": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 1024,
                "pattern": "^[A-Za-z0-9_-]+$"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "data",
          "next"
        ],
        "additionalProperties": false
      },
      "ListCursor": {
        "type": "string",
        "minLength": 1,
        "maxLength": 2048,
        "pattern": "^[A-Za-z0-9_-]+$",
        "description": "Opaque versioned ordinary-list position bound to the current publication, visible inventory, normalized request and limit. Not authentication. Restart on409; plain record IDs are not cursors."
      },
      "SupportedGeographyDataset": {
        "type": "object",
        "properties": {
          "sourceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "sourceReleaseId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "sourceVintage": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "geographyVintage": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "periodStart": {
            "type": "string",
            "format": "date"
          },
          "periodEnd": {
            "type": "string",
            "format": "date"
          },
          "metricIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 1000,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 256
            }
          }
        },
        "required": [
          "sourceId",
          "sourceReleaseId",
          "sourceVintage",
          "geographyVintage",
          "periodStart",
          "periodEnd",
          "metricIds"
        ],
        "additionalProperties": false
      },
      "ObservationValueInterval": {
        "type": "object",
        "properties": {
          "kind": {
            "const": "at_least"
          },
          "lowerBound": {
            "type": "number",
            "minimum": 0
          },
          "rawEstimate": {
            "type": "string",
            "pattern": "^\\d+(?:\\.0+)?$",
            "maxLength": 64
          },
          "rawMargin": {
            "enum": [
              "-333333333",
              "***"
            ]
          },
          "guidanceUrl": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://(?:www|www2|api)\\.census\\.gov/",
            "maxLength": 2048
          },
          "thresholdEvidenceUrl": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://(?:www|www2|api)\\.census\\.gov/",
            "maxLength": 2048
          },
          "thresholdEvidenceChecksum": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          }
        },
        "required": [
          "kind",
          "lowerBound",
          "rawEstimate",
          "rawMargin",
          "guidanceUrl",
          "thresholdEvidenceUrl",
          "thresholdEvidenceChecksum"
        ],
        "additionalProperties": false
      }
    },
    "responses": {
      "Error400": {
        "description": "Invalid request parameter (invalid_query, invalid_limit, invalid_cursor or invalid_comparison).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "Error403": {
        "description": "Export permission or the correction-form origin requirement does not permit this request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "Error404": {
        "description": "Unknown route or no approved place publication (route_not_found or place_not_found).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "Error405": {
        "description": "Method is not supported. Only GET and HEAD are accepted (method_not_allowed).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "Error409": {
        "description": "Publication/inventory changed, the retained publication is withheld, a metric/period is ambiguous, or a complete compatible ranking cohort is unavailable (publication_changed, inventory_changed, publication_unavailable, ambiguous_metric or incomplete_compatible_coverage).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "Error429": {
        "description": "Best-effort edge-IP request limit exceeded (rate_limited). Retry after the indicated interval.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        },
        "headers": {
          "Retry-After": {
            "description": "Retry interval in seconds.",
            "schema": {
              "type": "string",
              "example": "60"
            }
          }
        }
      },
      "Error503": {
        "description": "Publication database is unconfigured or temporarily unavailable (database_unavailable or publication_unavailable).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        },
        "headers": {
          "Retry-After": {
            "description": "Retry interval in seconds.",
            "schema": {
              "type": "string",
              "example": "60"
            }
          }
        }
      }
    }
  },
  "x-implementation-notes": {
    "methods": [
      "GET",
      "HEAD"
    ],
    "cors": "Same-origin browser use and server-to-server reads; cross-origin browser CORS access is not promised.",
    "rateLimit": {
      "requests": 60,
      "periodSeconds": 60,
      "key": "edge IP",
      "guarantee": "best effort; edge-local, not an account quota"
    },
    "snapshotRights": "Embedded source.rights is immutable publication-time evidence; PlaceResponse.effectivePermissions reflects current authorization."
  }
}
