BLS Time Series Data Response

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/bls/main/json-schema/bls-time-series-response.json",
  "title": "BLS Time Series Data Response",
  "description": "Response schema for the BLS Public Data API time series endpoints, covering both single-series GET and multi-series POST responses.",
  "type": "object",
  "required": ["status", "responseTime", "message"],
  "properties": {
    "status": {
      "type": "string",
      "title": "Response Status",
      "description": "Overall status of the API request.",
      "enum": ["REQUEST_SUCCEEDED", "REQUEST_FAILED_ERROR", "REQUEST_NOT_PROCESSED"],
      "examples": ["REQUEST_SUCCEEDED"]
    },
    "responseTime": {
      "type": "integer",
      "title": "Response Time",
      "description": "Server-side processing time in milliseconds.",
      "minimum": 0,
      "examples": [120, 84, 250]
    },
    "message": {
      "type": "array",
      "title": "Messages",
      "description": "Array of informational or error messages. Empty array indicates full success with no warnings.",
      "items": {
        "type": "string"
      },
      "examples": [
        [],
        ["Series does not exist for Series INVALID_ID"],
        ["Your daily query limit of 500 requests has been reached."]
      ]
    },
    "Results": {
      "type": "object",
      "title": "Results",
      "description": "Container for the returned series data.",
      "properties": {
        "series": {
          "type": "array",
          "title": "Series",
          "description": "Array of series results, one per requested series ID.",
          "items": {
            "$ref": "#/$defs/SeriesResult"
          }
        }
      }
    }
  },
  "$defs": {
    "SeriesResult": {
      "type": "object",
      "title": "Series Result",
      "description": "Data and metadata for a single BLS time series.",
      "required": ["seriesID", "data"],
      "properties": {
        "seriesID": {
          "type": "string",
          "title": "Series ID",
          "description": "The BLS series identifier.",
          "examples": ["LNS14000000", "CES0000000001", "CUUR0000SA0"]
        },
        "catalog": {
          "$ref": "#/$defs/SeriesCatalog"
        },
        "data": {
          "type": "array",
          "title": "Data Points",
          "description": "Array of time series observations, typically in reverse chronological order.",
          "items": {
            "$ref": "#/$defs/DataPoint"
          }
        }
      }
    },
    "SeriesCatalog": {
      "type": "object",
      "title": "Series Catalog",
      "description": "Metadata describing the series, returned when catalog=true in a v2 request.",
      "properties": {
        "series_title": {
          "type": "string",
          "examples": ["Unemployment Rate", "Total Nonfarm Employment"]
        },
        "series_id": {
          "type": "string",
          "examples": ["LNS14000000"]
        },
        "seasonality": {
          "type": "string",
          "enum": ["Seasonally Adjusted", "Not Seasonally Adjusted"],
          "examples": ["Seasonally Adjusted"]
        },
        "survey_name": {
          "type": "string",
          "examples": ["Labor Force Statistics including the National Unemployment Rate"]
        },
        "survey_abbreviation": {
          "type": "string",
          "examples": ["LN", "CE", "CU"]
        },
        "measure_data_type": {
          "type": "string",
          "examples": ["Percent", "Thousands", "Index"]
        },
        "commerce_industry": {
          "type": ["string", "null"],
          "examples": [null, "Manufacturing"]
        },
        "occupation": {
          "type": ["string", "null"],
          "examples": [null, "All Occupations"]
        },
        "cps_labor_force_status": {
          "type": ["string", "null"],
          "examples": ["Unemployment rate", null]
        },
        "demographic_race": {
          "type": ["string", "null"],
          "examples": ["All Races", "White", "Black or African American"]
        },
        "demographic_gender": {
          "type": ["string", "null"],
          "examples": ["Both Sexes", "Men", "Women"]
        },
        "demographic_origin": {
          "type": ["string", "null"],
          "examples": ["All Origins", "Hispanic or Latino", "Not Hispanic or Latino"]
        },
        "demographic_age": {
          "type": ["string", "null"],
          "examples": ["16 years and over", "20 to 24 years", "25 years and over"]
        },
        "demographic_education": {
          "type": ["string", "null"],
          "examples": [null, "Less than a High School Diploma", "College Graduates"]
        },
        "area": {
          "type": ["string", "null"],
          "examples": ["United States", "California", null]
        }
      }
    },
    "DataPoint": {
      "type": "object",
      "title": "Data Point",
      "description": "A single observation in a BLS time series.",
      "required": ["year", "period", "periodName", "value", "footnotes"],
      "properties": {
        "year": {
          "type": "string",
          "title": "Year",
          "description": "Four-digit year of the observation.",
          "pattern": "^\\d{4}$",
          "examples": ["2023", "2022", "2021"]
        },
        "period": {
          "type": "string",
          "title": "Period",
          "description": "Period code. Monthly: M01-M12. Quarterly: Q01-Q04. Annual: A01. Annual average: M13.",
          "pattern": "^(M(0[1-9]|1[0-3])|Q0[1-4]|A01|S0[12])$",
          "examples": ["M12", "M01", "Q01", "A01", "M13"]
        },
        "periodName": {
          "type": "string",
          "title": "Period Name",
          "description": "Human-readable name for the period.",
          "examples": ["December", "January", "1st Quarter", "Annual", "Annual Average"]
        },
        "latest": {
          "type": "string",
          "title": "Latest",
          "description": "Indicates whether this data point is the most recent observation for the series.",
          "enum": ["true", "false"],
          "examples": ["true", "false"]
        },
        "value": {
          "type": "string",
          "title": "Value",
          "description": "The statistical value for this observation, returned as a string to preserve precision.",
          "examples": ["3.7", "157244", "305.109", "-"]
        },
        "footnotes": {
          "type": "array",
          "title": "Footnotes",
          "description": "Array of footnotes qualifying this data point (e.g., preliminary or revised).",
          "items": {
            "$ref": "#/$defs/Footnote"
          }
        },
        "calculations": {
          "$ref": "#/$defs/DataPointCalculations"
        }
      }
    },
    "Footnote": {
      "type": "object",
      "title": "Footnote",
      "description": "A footnote qualifying a data observation.",
      "properties": {
        "code": {
          "type": "string",
          "title": "Footnote Code",
          "description": "Single-letter code: P=Preliminary, R=Revised, empty string=Final.",
          "examples": ["P", "R", ""]
        },
        "text": {
          "type": "string",
          "title": "Footnote Text",
          "description": "Full text of the footnote.",
          "examples": ["Preliminary", "Revised", ""]
        }
      }
    },
    "DataPointCalculations": {
      "type": "object",
      "title": "Data Point Calculations",
      "description": "Net and percent change calculations for a specific data point (returned when calculations=true in v2).",
      "properties": {
        "net_changes": {
          "type": "object",
          "title": "Net Changes",
          "description": "Net change from prior periods. Keys are number of periods back (e.g., '1' = one period, '3' = three periods, '12' = twelve months).",
          "additionalProperties": {
            "type": "string"
          },
          "examples": [{"1": "0.1", "3": "0.2", "12": "-0.4"}]
        },
        "pct_changes": {
          "type": "object",
          "title": "Percent Changes",
          "description": "Percent change from prior periods. Keys are number of periods back.",
          "additionalProperties": {
            "type": "string"
          },
          "examples": [{"1": "2.703", "3": "5.556", "12": "-9.756"}]
        }
      }
    }
  }
}