{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Deaf Data Lab API","version":"1.0.0","description":"Aggregate-only access to real National Deaf Center ACS PUMS estimates. Releases retain their source metadata and provide Census estimates with documented methodology and uncertainty. This API never returns synthetic substitutes or person-level records, and accepts no arbitrary SQL or raw PUMS variables."},"servers":[{"url":"/api/v1","description":"Same-origin public API"}],"tags":[{"name":"Catalog","description":"Definitions, releases, and geography metadata."},{"name":"Analysis","description":"Guarded aggregate queries and exports."}],"paths":{"/catalog":{"get":{"operationId":"getCatalog","tags":["Catalog"],"summary":"Get selected-release metrics, exact query capabilities, dimensions, and public limits","parameters":[{"name":"release","in":"query","description":"Select a real release. Defaults to the active release or an explicitly authorized candidate preview. Metrics, dimensions, filter combinations and geographies reflect only that release’s materialized coverage.","schema":{"$ref":"#/components/schemas/ReleaseId"}}],"responses":{"200":{"description":"Current public catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogResponse"}}}},"400":{"description":"Request does not match the v1 wire contract.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"The requested public resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"The server could not complete the request or produce a contract-conforming response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Required real release metadata, aggregate storage, or a public request safeguard is unavailable. Missing configuration never returns substitute values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/releases":{"get":{"operationId":"getReleases","tags":["Catalog"],"summary":"List analytical releases and the active pointer","responses":{"200":{"description":"Release history.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleasesResponse"}}}},"500":{"description":"The server could not complete the request or produce a contract-conforming response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Required real release metadata, aggregate storage, or a public request safeguard is unavailable. Missing configuration never returns substitute values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/definitions":{"get":{"operationId":"getDefinitions","tags":["Catalog"],"summary":"List versioned public definitions","parameters":[{"name":"release","in":"query","description":"Select a real release. Defaults to the active release or an explicitly authorized candidate preview. Metrics, dimensions, filter combinations and geographies reflect only that release’s materialized coverage.","schema":{"$ref":"#/components/schemas/ReleaseId"}},{"name":"q","in":"query","description":"Case-insensitive search across public definition metadata.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Definition summaries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefinitionsResponse"}}}},"400":{"description":"Request does not match the v1 wire contract.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"The requested public resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"The server could not complete the request or produce a contract-conforming response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Required real release metadata, aggregate storage, or a public request safeguard is unavailable. Missing configuration never returns substitute values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/definitions/{id}":{"get":{"operationId":"getDefinition","tags":["Catalog"],"summary":"Get one public definition","parameters":[{"name":"release","in":"query","description":"Select a real release. Defaults to the active release or an explicitly authorized candidate preview. Metrics, dimensions, filter combinations and geographies reflect only that release’s materialized coverage.","schema":{"$ref":"#/components/schemas/ReleaseId"}},{"name":"id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/StableId"}}],"responses":{"200":{"description":"Public definition without internal formulas or raw-variable access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefinitionDetail"}}}},"400":{"description":"Request does not match the v1 wire contract.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Definition not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"The server could not complete the request or produce a contract-conforming response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Required real release metadata, aggregate storage, or a public request safeguard is unavailable. Missing configuration never returns substitute values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/geographies":{"get":{"operationId":"getGeographies","tags":["Catalog"],"summary":"List supported aggregate geographies","parameters":[{"name":"release","in":"query","description":"Select a real release. Defaults to the active release or an explicitly authorized candidate preview. Metrics, dimensions, filter combinations and geographies reflect only that release’s materialized coverage.","schema":{"$ref":"#/components/schemas/ReleaseId"}},{"name":"type","in":"query","description":"Restrict results to one supported aggregate geography type.","schema":{"type":"string","enum":["nation","state","puma"]}},{"name":"q","in":"query","description":"Case-insensitive search across geography ID, name, and abbreviation.","schema":{"type":"string","maxLength":200}},{"name":"cursor","in":"query","description":"Use the nextCursor returned by the previous geography response.","schema":{"type":"string","minLength":1,"maxLength":512,"pattern":"^(?:0|[1-9][0-9]*)$"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":250,"default":50}}],"responses":{"200":{"description":"Paged geography catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeographiesResponse"}}}},"400":{"description":"Request does not match the v1 wire contract.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"The requested public resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"The server could not complete the request or produce a contract-conforming response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Required real release metadata, aggregate storage, or a public request safeguard is unavailable. Missing configuration never returns substitute values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/compare":{"post":{"operationId":"compareHistoricalPeriods","tags":["Analysis"],"summary":"Compare two complete source-backed ACS snapshots","description":"Absolute, percentage-point, relative, and Deaf–hearing disparity changes for comparable nonoverlapping periods. Preserves explicit not-comparable, suppressed, undefined, and absent-coverage states. Source query pagination is collected completely within export bounds; partial collections fail closed. JSON includes both source exports; CSV includes unrounded changes and source provenance. Common-dollar conversion requires a pinned authoritative factor. Candidate review status is retained. Intervals are pointwise Census approximations, not cross-release replicate pairing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HistoricalComparisonRequest"}}}},"responses":{"200":{"description":"Bounded historical comparison or CSV download, with exact comparison eligibility and source lineage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HistoricalComparisonResponse"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Request does not match the v1 wire contract.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body exceeds the 1 MB public API limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Valid request shape with a statistically unsupported combination.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Anonymous public rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"The server could not complete the request or produce a contract-conforming response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Required real release metadata, aggregate storage, or a public request safeguard is unavailable. Missing configuration never returns substitute values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/query":{"post":{"operationId":"runQuery","tags":["Analysis"],"summary":"Run a bounded aggregate query","description":"Values are resolved through a whitelisted internal model. Arbitrary SQL, raw variables, and person-level rows are not accepted.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"}}}},"responses":{"200":{"description":"Existing aggregate rows with stored replicate-weight uncertainty, suppression, source lineage and review status. releaseStatus, approvalLabel and approvedAt are always included by live responses; candidate status does not imply production approval.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryResponse"}}}},"400":{"description":"Request does not match the v1 wire contract.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body exceeds the 1 MB public API limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Valid request shape with a statistically unsupported combination.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Anonymous public rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"The server could not complete the request or produce a contract-conforming response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Required real release metadata, aggregate storage, or a public request safeguard is unavailable. Missing configuration never returns substitute values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/export":{"post":{"operationId":"createExport","tags":["Analysis"],"summary":"Download a bounded CSV or JSON aggregate export","description":"The selected format is returned directly as an attachment. JSON exports retain the canonical query lineage and aggregate row shape; CSV exports prepend the same lineage as comment records. Exports never contain person-level records.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportRequest"}}}},"responses":{"200":{"description":"Direct aggregate-only download in the requested format.","headers":{"Content-Disposition":{"description":"Attachment filename derived from the canonical query hash.","schema":{"type":"string"}},"X-Query-Hash":{"schema":{"$ref":"#/components/schemas/Sha256"}},"X-Export-Row-Count":{"schema":{"type":"integer","minimum":0,"maximum":10000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AggregateExport"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Request does not match the v1 wire contract.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request body exceeds the 1 MB public API limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Valid request shape with a statistically unsupported combination.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Anonymous public rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"The server could not complete the request or produce a contract-conforming response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Required real release metadata, aggregate storage, or a public request safeguard is unavailable. Missing configuration never returns substitute values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApiDocument","tags":["Catalog"],"summary":"Get this OpenAPI 3.1 document","responses":{"200":{"description":"OpenAPI 3.1 document.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"schemas":{"Breakdown":{"type":"object","additionalProperties":false,"required":["dimension"],"properties":{"dimension":{"$ref":"#/components/schemas/StableId"},"categories":{"type":"array","minItems":1,"maxItems":100,"uniqueItems":true,"items":{"$ref":"#/components/schemas/StableId"}}}},"Filter":{"type":"object","additionalProperties":false,"required":["dimension","categories"],"properties":{"dimension":{"$ref":"#/components/schemas/StableId"},"categories":{"type":"array","minItems":1,"maxItems":100,"uniqueItems":true,"items":{"$ref":"#/components/schemas/StableId"}}}},"StableId":{"type":"string","minLength":1,"maxLength":96,"pattern":"^[a-z][a-z0-9_]*$"},"ReleaseId":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z0-9][a-z0-9._-]{0,79}$"},"Sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"GeographyRef":{"type":"object","properties":{"type":{"enum":["nation","state","puma"],"type":"string"},"id":{"type":"string","minLength":1,"maxLength":16}},"required":["type","id"],"additionalProperties":false},"QueryRequest":{"type":"object","properties":{"release":{"$ref":"#/components/schemas/ReleaseId","description":"Immutable real aggregate release ID. Trend mode requires a verified product-trend-* multi-period release. Candidate releases require explicit preview authorization; synthetic releases are unavailable."},"product":{"enum":["acs1","acs5"],"type":"string"},"methodology":{"$ref":"#/components/schemas/ReleaseId"},"metric":{"$ref":"#/components/schemas/StableId"},"geographies":{"type":"array","items":{"$ref":"#/components/schemas/GeographyRef"},"minItems":1,"maxItems":4,"uniqueItems":true,"description":"Geography references must be unique. Rank and map requests require exactly one state or PUMA anchor, which selects the bounded all-state or all-PUMA scope."},"populations":{"type":"array","items":{"enum":["deaf","hearing"],"type":"string"},"minItems":1,"maxItems":2,"uniqueItems":true,"description":"Population IDs must be unique."},"breakdowns":{"type":"array","items":{"type":"object","properties":{"dimension":{"$ref":"#/components/schemas/StableId"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/StableId"},"minItems":1,"maxItems":100,"uniqueItems":true,"description":"Breakdown category IDs must be unique."}},"required":["dimension"],"additionalProperties":false},"maxItems":2,"uniqueItems":true,"description":"Exact duplicate breakdown selections are not allowed. The server also requires each breakdown dimension to appear at most once."},"filters":{"type":"array","items":{"type":"object","properties":{"dimension":{"$ref":"#/components/schemas/StableId"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/StableId"},"minItems":1,"maxItems":100,"uniqueItems":true,"description":"Filter category IDs must be unique."}},"required":["dimension","categories"],"additionalProperties":false},"maxItems":8,"uniqueItems":true,"description":"Exact duplicate filter selections are not allowed. The server also requires each filter dimension to appear at most once."},"mode":{"enum":["compare","trend","rank","map","table"],"type":"string"},"sort":{"type":"object","properties":{"field":{"enum":["geography","population","estimate","sample","reliability"],"type":"string"},"direction":{"enum":["ascending","descending"],"type":"string"}},"required":["field","direction"],"additionalProperties":false},"calculations":{"type":"array","items":{"enum":["difference","percentage_point_difference","ratio","percent_change"],"type":"string"},"maxItems":4,"uniqueItems":true,"description":"Calculation IDs must be unique."},"page":{"type":"object","properties":{"cursor":{"type":"string","minLength":1,"maxLength":512},"limit":{"type":"integer","minimum":1,"maximum":250,"default":50}},"required":[],"additionalProperties":false}},"required":["release","product","methodology","metric","geographies","populations","breakdowns","filters","mode","calculations"],"additionalProperties":false},"HistoricalComparisonRequest":{"type":"object","properties":{"before":{"$ref":"#/components/schemas/CanonicalQuery"},"after":{"$ref":"#/components/schemas/CanonicalQuery"},"change":{"enum":["absolute","relative","disparity"],"type":"string"},"commonDollarYear":{"type":"integer","minimum":2015,"maximum":2024},"format":{"enum":["json","csv"],"type":"string","default":"json"}},"required":["before","after","change"],"additionalProperties":false},"HistoricalComparisonResponse":{"type":"object","properties":{"sourceAvailability":{"type":"object","properties":{"version":{"const":"ndc-source-availability-2026.1"},"note":{"type":"string"}},"required":["version","note"],"additionalProperties":false},"persistence":{"type":"object","properties":{"extensionId":{"type":"string"},"manifestHash":{"type":"string"},"status":{"const":"candidate"},"requestVerification":{"type":"object","properties":{"selectedParts":{"type":"array","items":{"type":"string"}},"scope":{"type":"string"}},"required":["selectedParts","scope"],"additionalProperties":false},"persistedRows":{"type":"number"},"derivedRows":{"type":"number"}},"required":["extensionId","manifestHash","status","persistedRows","derivedRows"],"additionalProperties":false},"method":{"type":"object","properties":{"id":{"type":"string"},"confidenceLevel":{"const":0.95},"moeMultiplier":{"type":"number"},"covariance":{"type":"string"},"multipleComparisons":{"type":"string"},"sourceUrls":{"type":"array","items":{"type":"string","minLength":1,"maxLength":2048,"format":"uri"}}},"required":["id","confidenceLevel","moeMultiplier","covariance","multipleComparisons","sourceUrls"],"additionalProperties":false},"request":{"$ref":"#/components/schemas/HistoricalComparisonRequest"},"before":{"$ref":"#/components/schemas/AggregateExport"},"after":{"$ref":"#/components/schemas/AggregateExport"},"inflation":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"series":{"type":"string"},"sourceUrl":{"type":"string","minLength":1,"maxLength":2048,"format":"uri"},"note":{"type":"string"}},"required":["id","series","sourceUrl","note"],"additionalProperties":false},{"type":"null"}]},"warnings":{"type":"array","items":{"type":"string"}},"contextWarningCodes":{"type":"array","items":{"enum":["race_hispanic_2020","employment_questions_2019","weeks_worked_2019","pooled_2020_weighting"],"type":"string"}},"rows":{"type":"array","items":{"type":"object","properties":{"canonicalComparison":{"type":"object","properties":{"id":{"type":"string"},"beforeObservationId":{"type":"string"},"afterObservationId":{"type":"string"},"extensionManifestHash":{"type":"string"}},"required":["id","beforeObservationId","afterObservationId","extensionManifestHash"],"additionalProperties":false},"key":{"type":"string"},"geography":{"$ref":"#/components/schemas/GeographyRef"},"population":{"enum":["deaf","hearing","deaf_hearing_disparity"],"type":"string"},"breakdowns":{"type":"object","propertyNames":{"$ref":"#/components/schemas/StableId"},"additionalProperties":{"$ref":"#/components/schemas/StableId"}},"before":{"anyOf":[{"$ref":"#/components/schemas/ResultRow"},{"type":"null"}]},"after":{"anyOf":[{"$ref":"#/components/schemas/ResultRow"},{"type":"null"}]},"beforeAvailability":{"type":"object","properties":{"category":{"enum":["stable","unstable","suppressed","undefined","missing_input","unavailable","absent_coverage"],"type":"string"},"label":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"suppressionReason":{"anyOf":[{"enum":["denominator_below_threshold","zero_denominator","missing_input","derived_input_suppressed","median_zero_replicate_variance","zero_replicate_variance","unavailable"],"type":"string"},{"type":"null"}]}},"required":["category","label","description","suppressionReason"],"additionalProperties":false},"afterAvailability":{"type":"object","properties":{"category":{"enum":["stable","unstable","suppressed","undefined","missing_input","unavailable","absent_coverage"],"type":"string"},"label":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"suppressionReason":{"anyOf":[{"enum":["denominator_below_threshold","zero_denominator","missing_input","derived_input_suppressed","median_zero_replicate_variance","zero_replicate_variance","unavailable"],"type":"string"},{"type":"null"}]}},"required":["category","label","description","suppressionReason"],"additionalProperties":false},"status":{"enum":["comparable","not_comparable","suppressed","undefined","absent_coverage"],"type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit":{"enum":["people","percent","usd_period_end","years","percentage_points","ratio","usd_common_year"],"type":"string"},"commonDollarYear":{"anyOf":[{"type":"number"},{"type":"null"}]},"beforeFactor":{"anyOf":[{"type":"number"},{"type":"null"}]},"afterFactor":{"anyOf":[{"type":"number"},{"type":"null"}]},"estimate":{"anyOf":[{"type":"number"},{"type":"null"}]},"standardError":{"anyOf":[{"type":"number"},{"type":"null"}]},"marginOfError":{"anyOf":[{"type":"number"},{"type":"null"}]},"interval":{"anyOf":[{"type":"object","properties":{"lower":{"type":"number"},"upper":{"type":"number"}},"required":["lower","upper"],"additionalProperties":false},{"type":"null"}]},"reliability":{"anyOf":[{"enum":["stable","unstable"],"type":"string"},{"type":"null"}]},"includesZero":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["key","geography","population","breakdowns","before","after","status","reason","unit","commonDollarYear","beforeFactor","afterFactor","estimate","standardError","marginOfError","interval","reliability","includesZero"],"additionalProperties":false},"maxItems":20000}},"required":["method","request","before","after","inflation","warnings","contextWarningCodes","rows"],"additionalProperties":false},"CanonicalQuery":{"type":"object","properties":{"release":{"$ref":"#/components/schemas/ReleaseId","description":"Immutable real aggregate release ID. Trend mode requires a verified product-trend-* multi-period release. Candidate releases require explicit preview authorization; synthetic releases are unavailable."},"product":{"enum":["acs1","acs5"],"type":"string"},"methodology":{"$ref":"#/components/schemas/ReleaseId"},"metric":{"$ref":"#/components/schemas/StableId"},"geographies":{"type":"array","items":{"$ref":"#/components/schemas/GeographyRef"},"minItems":1,"maxItems":4,"uniqueItems":true,"description":"Geography references must be unique. Rank and map requests require exactly one state or PUMA anchor, which selects the bounded all-state or all-PUMA scope."},"populations":{"type":"array","items":{"enum":["deaf","hearing"],"type":"string"},"minItems":1,"maxItems":2,"uniqueItems":true,"description":"Population IDs must be unique."},"breakdowns":{"type":"array","items":{"type":"object","properties":{"dimension":{"$ref":"#/components/schemas/StableId"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/StableId"},"minItems":1,"maxItems":100,"uniqueItems":true,"description":"Breakdown category IDs must be unique."}},"required":["dimension"],"additionalProperties":false},"maxItems":2,"uniqueItems":true,"description":"Exact duplicate breakdown selections are not allowed. The server also requires each breakdown dimension to appear at most once."},"filters":{"type":"array","items":{"type":"object","properties":{"dimension":{"$ref":"#/components/schemas/StableId"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/StableId"},"minItems":1,"maxItems":100,"uniqueItems":true,"description":"Filter category IDs must be unique."}},"required":["dimension","categories"],"additionalProperties":false},"maxItems":8,"uniqueItems":true,"description":"Exact duplicate filter selections are not allowed. The server also requires each filter dimension to appear at most once."},"mode":{"enum":["compare","trend","rank","map","table"],"type":"string"},"sort":{"type":"object","properties":{"field":{"enum":["geography","population","estimate","sample","reliability"],"type":"string"},"direction":{"enum":["ascending","descending"],"type":"string"}},"required":["field","direction"],"additionalProperties":false},"calculations":{"type":"array","items":{"enum":["difference","percentage_point_difference","ratio","percent_change"],"type":"string"},"maxItems":4,"uniqueItems":true,"description":"Calculation IDs must be unique."}},"required":["release","product","methodology","metric","geographies","populations","breakdowns","filters","mode","calculations"],"additionalProperties":false},"ResultRow":{"type":"object","properties":{"geography":{"$ref":"#/components/schemas/GeographyRef"},"population":{"enum":["deaf","hearing"],"type":"string"},"periodLabel":{"type":"string","minLength":1,"maxLength":40},"breakdowns":{"type":"object","propertyNames":{"$ref":"#/components/schemas/StableId"},"additionalProperties":{"$ref":"#/components/schemas/StableId"}},"calculation":{"anyOf":[{"enum":["difference","percentage_point_difference","ratio","percent_change"],"type":"string"},{"type":"null"}]},"estimate":{"anyOf":[{"type":"number"},{"type":"null"}]},"unit":{"enum":["people","percent","usd_period_end","years","percentage_points","ratio"],"type":"string"},"standardError":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"confidenceLevel":{"const":0.95},"marginOfError":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"interval":{"anyOf":[{"type":"object","properties":{"lower":{"type":"number"},"upper":{"type":"number"}},"required":["lower","upper"],"additionalProperties":false},{"type":"null"}]},"unweightedSample":{"type":"integer","minimum":0,"maximum":9007199254740991},"weightedDenominator":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"reliability":{"enum":["stable","unstable","suppressed"],"type":"string"},"suppressionReason":{"anyOf":[{"enum":["denominator_below_threshold","zero_denominator","missing_input","derived_input_suppressed","median_zero_replicate_variance","zero_replicate_variance","unavailable"],"type":"string"},{"type":"null"}]}},"required":["geography","population","periodLabel","breakdowns","calculation","estimate","unit","standardError","confidenceLevel","marginOfError","interval","unweightedSample","weightedDenominator","reliability","suppressionReason"],"additionalProperties":false},"PageResponse":{"type":"object","properties":{"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"null"}]},"returned":{"type":"integer","minimum":0,"maximum":250},"limit":{"type":"integer","minimum":1,"maximum":250}},"required":["nextCursor","returned","limit"],"additionalProperties":false},"QueryResponse":{"type":"object","properties":{"queryHash":{"$ref":"#/components/schemas/Sha256"},"release":{"$ref":"#/components/schemas/ReleaseId"},"releaseStatus":{"enum":["candidate","approved","active","superseded","failed"],"type":"string"},"approvalLabel":{"type":"string","minLength":1,"maxLength":200},"approvedAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,9})?Z$"},{"type":"null"}]},"periodLabel":{"type":"string","minLength":1,"maxLength":40},"product":{"enum":["acs1","acs5"],"type":"string"},"pumaVintage":{"anyOf":[{"enum":[2010,2020],"type":"number"},{"type":"null"}]},"pumaBoundaryInventoryId":{"$ref":"#/components/schemas/Sha256"},"pumaBoundaryIds":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/components/schemas/Sha256"}},"pumaNames":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","minLength":1,"maxLength":300}},"methodologyVersion":{"$ref":"#/components/schemas/ReleaseId"},"definitionVersion":{"$ref":"#/components/schemas/ReleaseId"},"sourceManifestHash":{"$ref":"#/components/schemas/Sha256"},"sourceUrls":{"type":"array","items":{"type":"string","minLength":1,"maxLength":2048,"format":"uri"},"minItems":1,"maxItems":100},"citation":{"type":"string","minLength":1,"maxLength":2000},"calculatedAt":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,9})?Z$"},"calculationTimeMs":{"type":"number","minimum":0},"page":{"$ref":"#/components/schemas/PageResponse"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/ResultRow"},"maxItems":250}},"required":["queryHash","release","periodLabel","product","pumaVintage","methodologyVersion","definitionVersion","sourceManifestHash","sourceUrls","citation","calculatedAt","calculationTimeMs","page","rows"],"additionalProperties":false},"AggregateExport":{"type":"object","properties":{"queryHash":{"$ref":"#/components/schemas/Sha256"},"release":{"$ref":"#/components/schemas/ReleaseId"},"releaseStatus":{"enum":["candidate","approved","active","superseded","failed"],"type":"string"},"approvalLabel":{"type":"string","minLength":1,"maxLength":200},"approvedAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,9})?Z$"},{"type":"null"}]},"periodLabel":{"type":"string","minLength":1,"maxLength":40},"product":{"enum":["acs1","acs5"],"type":"string"},"pumaVintage":{"anyOf":[{"enum":[2010,2020],"type":"number"},{"type":"null"}]},"pumaBoundaryInventoryId":{"$ref":"#/components/schemas/Sha256"},"pumaBoundaryIds":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/components/schemas/Sha256"}},"pumaNames":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","minLength":1,"maxLength":300}},"methodologyVersion":{"$ref":"#/components/schemas/ReleaseId"},"definitionVersion":{"$ref":"#/components/schemas/ReleaseId"},"sourceManifestHash":{"$ref":"#/components/schemas/Sha256"},"sourceUrls":{"type":"array","items":{"type":"string","minLength":1,"maxLength":2048,"format":"uri"},"minItems":1,"maxItems":100},"citation":{"type":"string","minLength":1,"maxLength":2000},"calculatedAt":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,9})?Z$"},"calculationTimeMs":{"type":"number","minimum":0},"page":{"type":"object","properties":{"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"null"}]},"returned":{"type":"integer","minimum":0,"maximum":10000},"limit":{"type":"integer","minimum":1,"maximum":10000}},"required":["nextCursor","returned","limit"],"additionalProperties":false},"rows":{"type":"array","items":{"$ref":"#/components/schemas/ResultRow"},"maxItems":10000},"query":{"$ref":"#/components/schemas/CanonicalQuery"},"title":{"type":"string","minLength":1,"maxLength":300},"accessibleDescription":{"type":"string","minLength":1,"maxLength":2000}},"required":["queryHash","release","periodLabel","product","pumaVintage","methodologyVersion","definitionVersion","sourceManifestHash","sourceUrls","citation","calculatedAt","calculationTimeMs","page","rows","query","title","accessibleDescription"],"additionalProperties":false},"ExportRequest":{"type":"object","properties":{"query":{"$ref":"#/components/schemas/QueryRequest"},"format":{"enum":["csv","json"],"type":"string"},"maxRows":{"type":"integer","minimum":1,"maximum":10000,"default":10000}},"required":["query","format"],"additionalProperties":false},"DefinitionSummary":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StableId"},"title":{"type":"string","minLength":1,"maxLength":200},"shortDescription":{"type":"string","minLength":1,"maxLength":500},"taxonomy":{"$ref":"#/components/schemas/StableId"},"unit":{"enum":["people","percent","usd_period_end","years","percentage_points","ratio"],"type":"string"},"availablePopulations":{"type":"array","items":{"enum":["deaf","hearing"],"type":"string"},"minItems":1,"maxItems":2},"availability":{"type":"array","items":{"type":"object","properties":{"product":{"enum":["acs1","acs5"],"type":"string"},"geographies":{"type":"array","items":{"enum":["nation","state","puma"],"type":"string"},"minItems":1,"maxItems":3}},"required":["product","geographies"],"additionalProperties":false},"minItems":1}},"required":["id","title","shortDescription","taxonomy","unit","availablePopulations","availability"],"additionalProperties":false},"DefinitionDetail":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StableId"},"title":{"type":"string","minLength":1,"maxLength":200},"shortDescription":{"type":"string","minLength":1,"maxLength":500},"taxonomy":{"$ref":"#/components/schemas/StableId"},"unit":{"enum":["people","percent","usd_period_end","years","percentage_points","ratio"],"type":"string"},"availablePopulations":{"type":"array","items":{"enum":["deaf","hearing"],"type":"string"},"minItems":1,"maxItems":2},"availability":{"type":"array","items":{"type":"object","properties":{"product":{"enum":["acs1","acs5"],"type":"string"},"geographies":{"type":"array","items":{"enum":["nation","state","puma"],"type":"string"},"minItems":1,"maxItems":3}},"required":["product","geographies"],"additionalProperties":false},"minItems":1},"longDescription":{"type":"string","minLength":1,"maxLength":4000},"methodology":{"$ref":"#/components/schemas/ReleaseId"},"universe":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":500},"minAge":{"anyOf":[{"type":"integer","minimum":0,"maximum":99},{"type":"null"}]},"maxAge":{"anyOf":[{"type":"integer","minimum":0,"maximum":99},{"type":"null"}]}},"required":["label","minAge","maxAge"],"additionalProperties":false},"measure":{"enum":["count","rate","mean","median"],"type":"string"},"allowedBreakdowns":{"type":"array","items":{"$ref":"#/components/schemas/StableId"}},"requiredBreakdowns":{"type":"array","items":{"$ref":"#/components/schemas/StableId"}},"allowedFilters":{"type":"array","items":{"$ref":"#/components/schemas/StableId"}},"allowedCalculations":{"type":"array","items":{"enum":["difference","percentage_point_difference","ratio","percent_change"],"type":"string"}},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StableId"},"label":{"type":"string","minLength":1,"maxLength":300},"url":{"type":"string","minLength":1,"maxLength":2048,"format":"uri"}},"required":["id","label","url"],"additionalProperties":false},"minItems":1},"effectiveFrom":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"supersedes":{"anyOf":[{"$ref":"#/components/schemas/StableId"},{"type":"null"}]},"changeNote":{"type":"string","minLength":1,"maxLength":2000}},"required":["id","title","shortDescription","taxonomy","unit","availablePopulations","availability","longDescription","methodology","universe","measure","allowedBreakdowns","requiredBreakdowns","allowedFilters","allowedCalculations","sources","effectiveFrom","supersedes","changeNote"],"additionalProperties":false},"CatalogResponse":{"type":"object","properties":{"apiVersion":{"const":"v1"},"release":{"$ref":"#/components/schemas/ReleaseId"},"approvalLabel":{"type":"string","minLength":1,"maxLength":200},"queryCapabilities":{"type":"array","items":{"type":"object","properties":{"metric":{"$ref":"#/components/schemas/StableId"},"geographyTypes":{"type":"array","items":{"enum":["nation","state","puma"],"type":"string"}},"populations":{"type":"array","items":{"enum":["deaf","hearing"],"type":"string"}},"breakdowns":{"type":"array","items":{"$ref":"#/components/schemas/StableId"}},"filters":{"type":"array","items":{"type":"object","properties":{"dimension":{"$ref":"#/components/schemas/StableId"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/StableId"}}},"required":["dimension","categories"],"additionalProperties":false}},"calculations":{"type":"array","items":{"enum":["difference","percentage_point_difference","ratio","percent_change"],"type":"string"}}},"required":["metric","geographyTypes","populations","breakdowns","filters","calculations"],"additionalProperties":false}},"definitionVersion":{"$ref":"#/components/schemas/ReleaseId"},"methodologyVersion":{"$ref":"#/components/schemas/ReleaseId"},"definitions":{"type":"array","items":{"$ref":"#/components/schemas/DefinitionSummary"}},"dimensions":{"type":"array","items":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StableId"},"title":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","minLength":1,"maxLength":1000},"dynamic":{"type":"boolean"},"filterable":{"type":"boolean"},"breakdown":{"type":"boolean"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StableId"},"label":{"type":"string","minLength":1,"maxLength":300}},"required":["id","label"],"additionalProperties":false}}},"required":["id","title","description","dynamic","filterable","breakdown","categories"],"additionalProperties":false}},"limits":{"type":"object","properties":{"interactiveMaxRows":{"const":250},"exportMaxRows":{"const":10000},"maxBreakdowns":{"const":2},"maxPinnedGeographies":{"const":4}},"required":["interactiveMaxRows","exportMaxRows","maxBreakdowns","maxPinnedGeographies"],"additionalProperties":false}},"required":["apiVersion","definitionVersion","methodologyVersion","definitions","dimensions","limits"],"additionalProperties":false},"ReleasesResponse":{"type":"object","properties":{"activeRelease":{"anyOf":[{"$ref":"#/components/schemas/ReleaseId"},{"type":"null"}]},"releases":{"type":"array","items":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ReleaseId"},"product":{"enum":["acs1","acs5"],"type":"string"},"periodStart":{"type":"string","pattern":"^\\d{4}$"},"periodEnd":{"type":"string","pattern":"^\\d{4}$"},"periodLabel":{"type":"string","minLength":1,"maxLength":40},"status":{"enum":["candidate","approved","active","superseded","failed"],"type":"string"},"pumaVintage":{"anyOf":[{"enum":[2010,2020],"type":"number"},{"type":"null"}]},"pumaBoundaryInventoryId":{"$ref":"#/components/schemas/Sha256"},"methodologyVersion":{"$ref":"#/components/schemas/ReleaseId"},"definitionVersion":{"$ref":"#/components/schemas/ReleaseId"},"sourceManifestHash":{"$ref":"#/components/schemas/Sha256"},"approvedAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,9})?Z$"},{"type":"null"}]},"changeReportUrl":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048,"format":"uri"},{"type":"null"}]},"demonstration":{"type":"boolean"},"note":{"type":"string","minLength":1,"maxLength":1000}},"required":["id","product","periodStart","periodEnd","periodLabel","status","pumaVintage","methodologyVersion","definitionVersion","sourceManifestHash","approvedAt","changeReportUrl","demonstration","note"],"additionalProperties":false}}},"required":["activeRelease","releases"],"additionalProperties":false},"DefinitionsResponse":{"type":"object","properties":{"definitionVersion":{"$ref":"#/components/schemas/ReleaseId"},"definitions":{"type":"array","items":{"$ref":"#/components/schemas/DefinitionSummary"}}},"required":["definitionVersion","definitions"],"additionalProperties":false},"GeographiesResponse":{"type":"object","properties":{"release":{"$ref":"#/components/schemas/ReleaseId"},"geographies":{"type":"array","items":{"type":"object","properties":{"type":{"enum":["nation","state","puma"],"type":"string"},"id":{"type":"string","minLength":1,"maxLength":16},"name":{"type":"string","minLength":1,"maxLength":300},"abbreviation":{"anyOf":[{"type":"string","minLength":1,"maxLength":10},{"type":"null"}]},"stateFips":{"anyOf":[{"type":"string","pattern":"^\\d{2}$"},{"type":"null"}]},"pumaVintage":{"anyOf":[{"enum":[2010,2020],"type":"number"},{"type":"null"}]},"pumaBoundaryInventoryId":{"$ref":"#/components/schemas/Sha256"},"boundaryId":{"$ref":"#/components/schemas/Sha256"},"product":{"enum":["acs1","acs5"],"type":"string"}},"required":["type","id","name","abbreviation","stateFips","pumaVintage","product"],"additionalProperties":false},"maxItems":250},"page":{"$ref":"#/components/schemas/PageResponse"}},"required":["release","geographies","page"],"additionalProperties":false},"ApiError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"enum":["invalid_request","invalid_combination","not_found","rate_limited","export_limit_exceeded","release_unavailable","internal_error"],"type":"string"},"message":{"type":"string","minLength":1,"maxLength":1000},"status":{"type":"integer","minimum":400,"maximum":599},"requestId":{"type":"string","minLength":1,"maxLength":128},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":80},"path":{"type":"string","minLength":1,"maxLength":300},"message":{"type":"string","minLength":1,"maxLength":1000}},"required":["code","path","message"],"additionalProperties":false},"maxItems":100}},"required":["code","message","status"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}