{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://economy.com/schemas/moodys/time-series.json",
  "title": "Moody's Analytics Time Series",
  "description": "Schema for a Moody's Analytics Data Buffet time series response, representing economic, demographic, or financial observations and forecasts over a date range with associated metadata.",
  "type": "object",
  "required": [
    "mnemonic",
    "description",
    "frequency",
    "data"
  ],
  "properties": {
    "mnemonic": {
      "type": "string",
      "description": "The unique series mnemonic identifier following the Data Buffet naming convention. Mnemonics encode the concept, geography, and source of the data.",
      "examples": [
        "FGDP_US",
        "EMPLPAY.IUSA",
        "UCUR.IUSA",
        "FHPI_US"
      ]
    },
    "description": {
      "type": "string",
      "description": "Human-readable description of the time series including the indicator name, geographic scope, and data source.",
      "examples": [
        "Gross Domestic Product, United States",
        "Total Nonfarm Payrolls, United States",
        "Consumer Price Index, All Urban Consumers, United States"
      ]
    },
    "frequency": {
      "type": "string",
      "description": "The temporal frequency of the observations in the data array. Indicates how often data points are recorded or reported.",
      "enum": [
        "Annual",
        "Quarterly",
        "Monthly",
        "Weekly",
        "Daily"
      ]
    },
    "source": {
      "type": "string",
      "description": "The original data source or statistical agency that produces the raw data.",
      "examples": [
        "Bureau of Labor Statistics",
        "Bureau of Economic Analysis",
        "Federal Reserve Board",
        "International Monetary Fund",
        "Eurostat",
        "Moody's Analytics"
      ]
    },
    "geography": {
      "type": "string",
      "description": "The geographic area the series covers. Can range from global aggregates to subnational regions.",
      "examples": [
        "United States",
        "United Kingdom",
        "European Union",
        "China",
        "California",
        "New York-Newark-Jersey City, NY-NJ-PA MSA"
      ]
    },
    "geographyCode": {
      "type": "string",
      "description": "Standardized geographic area code (ISO 3166 country code or FIPS state/county code).",
      "examples": [
        "US",
        "GB",
        "EU",
        "CN",
        "US-CA"
      ]
    },
    "units": {
      "type": "string",
      "description": "The unit of measurement for the series values, describing what the numeric values represent.",
      "examples": [
        "Billions of Chained 2017 Dollars",
        "Thousands of Persons",
        "Index 1982-84=100",
        "Percent",
        "Millions of Units"
      ]
    },
    "transformation": {
      "type": "string",
      "description": "The mathematical transformation applied to the original data, if any.",
      "enum": [
        "Level",
        "SimpleDifference",
        "PercentChange",
        "AnnualizedGrowth",
        "YearOverYearPercentChange",
        "CompoundAnnualGrowthRate"
      ]
    },
    "category": {
      "type": "string",
      "description": "The broad economic or demographic category the series belongs to.",
      "examples": [
        "National Accounts",
        "Labor Markets",
        "Prices and Inflation",
        "Housing",
        "Financial Markets",
        "Demographics",
        "Trade",
        "Government Finance"
      ]
    },
    "startDate": {
      "type": "string",
      "format": "date",
      "description": "The earliest observation date in the returned data range."
    },
    "endDate": {
      "type": "string",
      "format": "date",
      "description": "The latest observation or forecast date in the returned data range."
    },
    "vintage": {
      "type": "string",
      "format": "date",
      "description": "The vintage date of the data, representing when this revision of the data was published. Enables tracking of historical data revisions."
    },
    "lastUpdated": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp indicating when the series was last updated in the Data Buffet repository."
    },
    "isForecast": {
      "type": "boolean",
      "description": "Whether the series includes forecast values generated by Moody's Analytics proprietary macroeconomic models."
    },
    "forecastStartDate": {
      "type": "string",
      "format": "date",
      "description": "The date at which forecast data begins within the series. All observations before this date are historical actuals."
    },
    "seasonalAdjustment": {
      "type": "string",
      "description": "Whether and how the data has been seasonally adjusted.",
      "enum": [
        "Seasonally Adjusted",
        "Not Seasonally Adjusted",
        "Seasonally Adjusted Annual Rate"
      ]
    },
    "data": {
      "type": "array",
      "description": "Array of chronologically ordered date-value pairs representing the time series observations and/or forecasts. Each element corresponds to one period at the series frequency.",
      "items": {
        "$ref": "#/$defs/Observation"
      }
    }
  },
  "$defs": {
    "Observation": {
      "type": "object",
      "title": "Time Series Observation",
      "description": "A single data point in the time series representing an observed historical value, a preliminary estimate, or a forecast for a specific date period.",
      "required": [
        "date",
        "value"
      ],
      "properties": {
        "date": {
          "type": "string",
          "format": "date",
          "description": "The observation date in YYYY-MM-DD format. For frequencies coarser than daily, this represents the period start date (e.g., 2024-01-01 for Q1 2024 or January 2024).",
          "examples": [
            "2024-01-01",
            "2024-04-01",
            "2024-07-15"
          ]
        },
        "value": {
          "type": ["number", "null"],
          "description": "The observed, estimated, or forecast value for this period. Null indicates missing or unavailable data.",
          "examples": [
            22038.2,
            157.5,
            3.7,
            null
          ]
        },
        "status": {
          "type": "string",
          "description": "Indicates whether this data point is a confirmed historical observation, a preliminary estimate subject to revision, or a model-generated forecast.",
          "enum": [
            "History",
            "Forecast",
            "Preliminary"
          ]
        }
      }
    }
  }
}