{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/openephemeris-com/json-schema/openephemeris-com-ba-zi-annual-pillar-request-schema.json",
  "title": "BaZiAnnualPillarRequest",
  "description": "Request for the Liu Nian (流年) annual pillar. Supply year alone for the sexagenary label of that Gregorian year, or add month/day (and optionally hour) to classify a specific moment under the chosen year_boundary.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/openephemeris-com-chinese-api-openapi.yml#/components/schemas/BaZiAnnualPillarRequest",
  "properties": {
    "day": {
      "description": "Optional day of month. When supplied together with month, the moment is classified under year_boundary and the resolved BaZi year is returned. Must be supplied together with month.",
      "maximum": 31,
      "minimum": 1,
      "type": "integer"
    },
    "hour": {
      "default": 12,
      "description": "Optional hour (0–23), only meaningful when month and day are supplied. Defaults to 12 (noon).",
      "maximum": 23,
      "minimum": 0,
      "type": "integer"
    },
    "month": {
      "description": "Optional month (1–12). When supplied together with day, the moment is classified under year_boundary and the resolved BaZi year is returned. Must be supplied together with day.",
      "maximum": 12,
      "minimum": 1,
      "type": "integer"
    },
    "year": {
      "description": "Gregorian year for the Liu Nian calculation. When month and day are supplied, the response echoes the resolved BaZi year, which may differ from this value.",
      "maximum": 9999,
      "minimum": 1,
      "type": "integer"
    },
    "year_boundary": {
      "$ref": "#/$defs/BaZiYearBoundaryEnum",
      "default": "lichun",
      "description": "Year-pillar boundary convention used when month and day are supplied. Accepted and ignored when they are absent, because the sexagenary label of a whole Gregorian year is boundary-independent — the boundary only matters when classifying a moment."
    }
  },
  "required": [
    "year"
  ],
  "type": "object",
  "$defs": {
    "BaZiYearBoundaryEnum": {
      "description": "Year-pillar boundary convention. lichun rolls the year pillar at the Lichun (立春) solar term, around 4 February; cny rolls it at Chinese New Year.",
      "enum": [
        "lichun",
        "cny"
      ],
      "title": "BaZiYearBoundaryEnum",
      "type": "string"
    }
  }
}