VedicChartRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/openephemeris-com/json-schema/openephemeris-com-vedic-chart-request-schema.json",
  "title": "VedicChartRequest",
  "description": "Request body for a Vedic natal chart.\n\nExactly one of `datetime_utc` (an instant the caller has already converted) or `datetime_local` (a naive local wall-clock time the SERVER converts, using the required birth coordinates and the historical-correction overlay) is required. Prefer `datetime_local` for a birth time read off a certificate: only the server-side conversion can apply the pre-1970 corrections, so a 1961 Minnesota birth resolves to CST where raw IANA tzdata says CDT.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/openephemeris-com-openapi.json#/components/schemas/VedicChartRequest",
  "properties": {
    "ashtakavarga_rules": {
      "default": "raman",
      "description": "Bindu table for `include: [\"ashtakavarga\"]`. raman (default): B.V. Raman, \"Hindu Predictive Astrology\" ch. 26. bphs: Brihat Parashara Hora Shastra ch. 66 as translated (Ranjan 1992); it differs from Raman in five contributor lists of the Moon and Mercury, every total is the same.",
      "enum": [
        "raman",
        "bphs"
      ],
      "type": "string",
      "x-enum-varnames": [
        "VedicAshtakavargaRulesRaman",
        "VedicAshtakavargaRulesBphs"
      ]
    },
    "ayanamsa": {
      "anyOf": [
        {
          "type": "string"
        }
      ],
      "default": "lahiri",
      "description": "Ayanamsa system for tropical-to-sidereal conversion. Supported: lahiri (default), fagan_bradley, krishnamurti (KP old), krishnamurti_vp291 (KP new), raman, yukteshwar.",
      "title": "Ayanamsa"
    },
    "dasha": {
      "allOf": [
        {
          "$ref": "#/$defs/VedicDashaRequest"
        }
      ],
      "description": "Optional. Adds a Vimshottari dasha timeline to the response. No extra credit."
    },
    "datetime_local": {
      "description": "Naive local wall-clock birth datetime (YYYY-MM-DDTHH:MM:SS, no zone suffix), resolved by the server at `latitude`/`longitude`. Mutually exclusive with `datetime_utc` — exactly one of the two is required. The zone comes from the sibling `timezone` field when supplied, otherwise from the coordinates; the historical-correction overlay is consulted for pre-1970 dates. The resolution is echoed back in `metadata` as tz_confidence / tz_rule_source / tz_resolved_offset / resolved_utc.",
      "title": "Datetime Local",
      "type": "string"
    },
    "datetime_utc": {
      "description": "Birth date-time in ISO 8601 UTC format. Example: '1990-01-15T08:30:00'. The field name pins the zone, so a zone-less value here is read as UTC. Mutually exclusive with `datetime_local`.",
      "title": "Datetime Utc",
      "type": "string"
    },
    "ekadhipatya_rule": {
      "default": "pvr",
      "description": "Ekadhipatya shodhana rule for `include: [\"ashtakavarga\"]` (#1219). pvr (default; P.V.R. Narasimha Rao, VAIA 12.7.2, reproduces his printed Chart 7 answers): an empty sign higher than its occupied twin takes the twin's value; two empty unequal signs both take the lower. santhanam (BPHS 68 as R. Santhanam translates it): the empty higher sign loses the occupied one's value; two empty unequal signs both take the smaller. Occupied means a graha Sun to Saturn or the lagna.",
      "enum": [
        "pvr",
        "santhanam"
      ],
      "type": "string",
      "x-enum-varnames": [
        "VedicEkadhipatyaRulePvr",
        "VedicEkadhipatyaRuleSanthanam"
      ]
    },
    "include": {
      "description": "Optional extra strength tables, no extra credit. ashtakavarga: Bhinnashtakavarga of the seven grahas, Sarvashtakavarga and the Lagna's own ashtakavarga (rules from `ashtakavarga_rules`). shadbala: the six-fold strength of Sun to Saturn in virupas and rupas, every sub-bala listed, after B.V. Raman, \"Graha and Bhava Balas\" (1942). bhava_bala: the strength of the twelve houses (Bhavadhipati, Dig and Drishti bala, same source; computes Shadbala internally). Shadbala and Bhava Bala need a sunrise and sunset on the birth day, so a polar day or night is a 422.",
      "items": {
        "enum": [
          "ashtakavarga",
          "shadbala",
          "bhava_bala"
        ],
        "type": "string",
        "x-enum-varnames": [
          "VedicIncludeAshtakavarga",
          "VedicIncludeShadbala",
          "VedicIncludeBhavaBala"
        ]
      },
      "maxItems": 3,
      "type": "array",
      "uniqueItems": true
    },
    "include_visual": {
      "description": "When true, renders an inline South Indian Rashi grid SVG alongside the chart.",
      "type": "boolean"
    },
    "latitude": {
      "description": "Birth latitude in decimal degrees (north positive).",
      "maximum": 90,
      "minimum": -90,
      "title": "Latitude",
      "type": "number"
    },
    "longitude": {
      "description": "Birth longitude in decimal degrees (east positive).",
      "maximum": 180,
      "minimum": -180,
      "title": "Longitude",
      "type": "number"
    },
    "node_type": {
      "default": "mean",
      "description": "Which lunar node Ketu is taken from (Ketu is that node + 180 degrees). mean (default) is the traditional Jyotish node, always retrograde, and what Drik Panchang uses; true is the osculating node, which wobbles by up to about 1.5 degrees. Both Rahu rows (North Node (Mean) and North Node (True)) are still returned in the legacy roster; only Ketu, and the Rahu row in the classical roster, follow this choice. Neither node changes any Vimshottari date (the Moon alone decides those).",
      "enum": [
        "mean",
        "true"
      ],
      "type": "string"
    },
    "roster": {
      "default": "legacy",
      "description": "legacy (default) returns the existing rows (Sun to Saturn, Uranus, Neptune, Pluto, both North Nodes, Chiron) plus one Ketu row. classical returns only the nine Jyotish grahas: Sun to Saturn, the node chosen by node_type, and Ketu.",
      "enum": [
        "legacy",
        "classical"
      ],
      "type": "string"
    },
    "timezone": {
      "$ref": "#/$defs/TimezoneInput",
      "description": "Zone that governs `datetime_local`. Optional — when omitted the zone is looked up from `latitude`/`longitude`. Supply it to override that lookup (a border town, a historical place name), or to force `time_standard`/`fold_preference`. Ignored when `datetime_utc` is used."
    },
    "vargas": {
      "description": "Optional. Divisional charts (vargas) to add, by number: any of 1, 2, 3, 4, 7, 9, 10, 12, 16, 20, 24, 27, 30, 40, 45, 60. Each planet and the lagna get their varga sign, degree and part in the Parashara reading of Brihat Parashara Hora Shastra (the only school implemented; contested variants are not offered). No extra credit.",
      "items": {
        "maximum": 60,
        "minimum": 1,
        "type": "integer"
      },
      "maxItems": 16,
      "type": "array",
      "uniqueItems": true
    },
    "visual_config": {
      "$ref": "#/$defs/VisualRenderConfig"
    }
  },
  "required": [
    "latitude",
    "longitude"
  ],
  "type": "object",
  "$defs": {
    "TimezoneInput": {
      "additionalProperties": false,
      "description": "Timezone input using IANA names or UTC offsets.",
      "properties": {
        "fold_preference": {
          "description": "Which occurrence to use when the naive local datetime falls in a fall-back fold (a repeated hour): 'earlier' (default — first occurrence) or 'later'. Only meaningful for naive datetimes; the response reports datetime_status=ambiguous_fold either way so the ambiguity can be surfaced to the user.",
          "enum": [
            "earlier",
            "later"
          ],
          "title": "Fold Preference",
          "type": "string"
        },
        "iana_name": {
          "anyOf": [
            {
              "maxLength": 128,
              "type": "string"
            }
          ],
          "description": "IANA timezone name",
          "title": "Iana Name"
        },
        "time_standard": {
          "description": "How to interpret a naive local datetime when this zone is applied. 'auto' (default): resolve through the historical-correction overlay where one covers the region/era, then IANA tzdata. 'standard': force the zone's standard (non-daylight) offset — for callers who KNOW the recorded time was standard time regardless of what tzdata believes. 'daylight': force standard+1h. Forcing either marks the resolution tz_confidence=client_override. Ignored when the datetime carries its own Z/±HH:MM suffix or when utc_offset is used.",
          "enum": [
            "auto",
            "standard",
            "daylight"
          ],
          "title": "Time Standard",
          "type": "string"
        },
        "utc_offset": {
          "anyOf": [
            {
              "type": "number"
            }
          ],
          "description": "UTC offset in hours",
          "title": "Utc Offset"
        }
      },
      "title": "TimezoneInput",
      "type": "object"
    },
    "VedicDashaRequest": {
      "additionalProperties": false,
      "description": "Ask for a dasha timeline. vimshottari (default) and yogini start from the birth Moon's nakshatra: the first lord is found from it and the part of that period already elapsed is the Moon's fraction through the nakshatra; every sub-period is the parent times the sub-lord's years over the cycle total (120 or 36). chara is the Jaimini sign dasha by K.N. Rao's method, started from the lagna sign at birth. Choices the schools disagree on are request fields and are echoed: the length of a dasha year (year_basis), the ayanamsa (the request's `ayanamsa`), and for chara the second-cycle rule and the karaka scheme.",
      "properties": {
        "as_of_utc": {
          "description": "Optional instant (ISO 8601; a zone-less value is read as UTC, as in datetime_utc). When given, `running` lists the period at every level that contains it. Never defaults to now. Must fall inside the timeline (birth to the end of the ninth mahadasha).",
          "type": "string"
        },
        "chara_method": {
          "default": "kn_rao",
          "description": "chara only (#1219). kn_rao (default): K.N. Rao's Chara dasha, unchanged. pvr: Parashara's Chara dasha as P.V.R. Narasimha Rao gives it and Jagannatha Hora computes it (2005): K.N. Rao's order and counting plus a year for an exalted lord and one off for a debilitated one, Scorpio and Aquarius by PVR's stronger co-lord rules; mahadashas only (depth 1). rath: Sanjay Rath's Chara dasha, which is Narayana (Padakrama) dasha (Rath, Crux of Vedic Astrology): it starts from the stronger of the lagna and the 7th, moves one by one, every 6th or by trines as the seed is movable, fixed or dual, with the Saturn and Ketu exceptions; antardashas from the sign of the stronger lord (VAIA ch. 18). pvr and rath default the second cycle to twelve_minus.",
          "enum": [
            "kn_rao",
            "pvr",
            "rath"
          ],
          "type": "string",
          "x-enum-varnames": [
            "VedicCharaMethodKnRao",
            "VedicCharaMethodPvr",
            "VedicCharaMethodRath"
          ]
        },
        "chara_second_cycle": {
          "description": "chara only. Years of each sign in the second cycle: repeat gives the first-cycle years again, as in K.N. Rao's published tables (the default for kn_rao); twelve_minus gives 12 minus them (P.V.R. Narasimha Rao's rule, VAIA 18.2.2; the default for pvr and rath); a sign with 12 first-cycle years then has no second-cycle period.",
          "enum": [
            "repeat",
            "twelve_minus"
          ],
          "type": "string",
          "x-enum-varnames": [
            "VedicCharaSecondCycleRepeat",
            "VedicCharaSecondCycleTwelveMinus"
          ]
        },
        "depth": {
          "default": 2,
          "description": "Deepest level listed: 1 mahadasha, 2 antardasha, 3 pratyantardasha. Level 3 lists up to 729 periods for vimshottari. chara goes to 2 (twelve equal antardashas per sign).",
          "maximum": 3,
          "minimum": 1,
          "type": "integer"
        },
        "karaka_scheme": {
          "default": 7,
          "description": "chara only. Jaimini chara karakas returned with the dasha: 7 (default; K.N. Rao: Sun to Saturn, Atmakaraka to Darakaraka with no Pitrikaraka) or 8 (adds Rahu, measured as 30 minus its degree in its sign, and the Pitrikaraka; P.V.R. Narasimha Rao). The karakas do not change the chara periods in K.N. Rao's method.",
          "enum": [
            7,
            8
          ],
          "type": "integer",
          "x-enum-varnames": [
            "VedicKarakaScheme7",
            "VedicKarakaScheme8"
          ]
        },
        "system": {
          "default": "vimshottari",
          "description": "Dasha system. vimshottari: 120 years, nine lords. yogini: 36-year cycle of the eight yoginis (BPHS 46.198-200), Mangala 1 year to Sankata 8, repeated until 120 years after birth. chara: Jaimini Chara dasha, K.N. Rao's method (signs, 1 to 12 years each, two cycles or more).",
          "enum": [
            "vimshottari",
            "yogini",
            "chara"
          ],
          "type": "string"
        },
        "year_basis": {
          "default": "julian",
          "description": "Length of a dasha year. julian 365.25 days (default), savana 360, sidereal_year 365.256363, tropical_year 365.242189. They differ by up to 5.25 days per year of age.",
          "enum": [
            "julian",
            "savana",
            "sidereal_year",
            "tropical_year"
          ],
          "type": "string"
        }
      },
      "title": "VedicDashaRequest",
      "type": "object"
    },
    "VisualRenderConfig": {
      "additionalProperties": false,
      "description": "Optional rendering preferences for inline chart visuals.",
      "properties": {
        "format": {
          "default": "svg",
          "description": "Output encoding: \"svg\" (default) or \"png\". PNG requires resvg on the server.",
          "enum": [
            "svg",
            "png"
          ],
          "title": "Format",
          "type": "string"
        },
        "layout": {
          "default": "graph",
          "description": "Bodygraph composition: \"graph\" (default) is the classic layout; \"mandala\" nests the same diagram inside concentric rings. Ignored for wheel renders. Honored on natal and overlay (transit, connection) bodygraph paths.",
          "enum": [
            "graph",
            "mandala"
          ],
          "title": "Layout",
          "type": "string"
        },
        "size": {
          "default": 800,
          "description": "Canvas pixel dimension. Range [200, 4000]. Default 800.",
          "maximum": 4000,
          "minimum": 200,
          "title": "Size",
          "type": "integer"
        },
        "theme": {
          "default": "light",
          "description": "Colour palette: \"light\" (default) or \"dark\".",
          "enum": [
            "light",
            "dark"
          ],
          "title": "Theme",
          "type": "string"
        }
      },
      "title": "VisualRenderConfig",
      "type": "object"
    }
  }
}