{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/openephemeris-com/json-schema/openephemeris-com-venus-eight-year-star-response-schema.json",
  "title": "VenusEightYearStarResponse",
  "description": "Success response containing the 5-point Venus Star pattern.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/openephemeris-com-venus-cycles-api-openapi.yml#/components/schemas/VenusEightYearStarResponse",
  "properties": {
    "calculation_metadata": {
      "allOf": [
        {
          "$ref": "#/$defs/CalculationMetadata"
        }
      ],
      "description": "Execution timing and precision metadata"
    },
    "success": {
      "default": true,
      "description": "Status of the calculation",
      "title": "Success",
      "type": "boolean"
    },
    "vertices": {
      "description": "The 5 conjunctions forming the current pentagram",
      "items": {
        "$ref": "#/$defs/ConjunctionEvent"
      },
      "title": "Vertices",
      "type": "array"
    }
  },
  "required": [
    "vertices",
    "calculation_metadata"
  ],
  "type": "object",
  "$defs": {
    "AyanamsaEnum": {
      "description": "Supported sidereal ayanamsa options (krishnamurti is KP old, krishnamurti_vp291 KP new). All six are computed from the same IAU 2006 general-precession model, so each is epoch-dependent rather than a frozen constant; they differ by up to ~2.3 degrees, which is enough to move a body across a sign boundary. Defaults to lahiri when zodiac_type is sidereal and no system is named.",
      "enum": [
        "lahiri",
        "fagan_bradley",
        "krishnamurti",
        "krishnamurti_vp291",
        "raman",
        "yukteshwar"
      ],
      "title": "AyanamsaEnum",
      "type": "string"
    },
    "CalculationMetadata": {
      "additionalProperties": true,
      "description": "Metadata about chart calculations.\n\nRelaxed to allow minimal fields used by tests while remaining forward-compatible.",
      "properties": {
        "ascendant_on_left": {
          "default": true,
          "description": "When true (default), the Ascendant is placed at the 9 o'clock (West/left) position � matching the convention used by Astro.com, Solar Fire, and all major astrology software. Set to false to use the ecliptic-fixed (Aries-pinned) orientation instead.",
          "title": "Ascendant on Left",
          "type": [
            "boolean",
            "null"
          ]
        },
        "ayanamsa": {
          "anyOf": [
            {
              "$ref": "#/$defs/AyanamsaEnum"
            },
            {
              "type": "string"
            }
          ],
          "description": "Sidereal ayanamsa selection",
          "title": "Ayanamsa"
        },
        "calculation_time": {
          "anyOf": [
            {
              "type": "number"
            }
          ],
          "description": "Legacy calculation time in seconds",
          "title": "Calculation Time"
        },
        "calculation_time_ms": {
          "anyOf": [
            {
              "type": "number"
            }
          ],
          "description": "Processing time at the orchestrator layer in milliseconds",
          "title": "Calculation Time Ms"
        },
        "calculation_time_utc": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            }
          ],
          "description": "UTC timestamp when the calculation executed",
          "title": "Calculation Time Utc"
        },
        "coordinate_reference_frame": {
          "anyOf": [
            {
              "type": "string"
            }
          ],
          "description": "Coordinate frame the positions are expressed in, always the TRUE ecliptic of date: geocentric_true_ecliptic_of_date (apparent place from the Earth's centre), topocentric_true_ecliptic_of_date (apparent place from the observer, with diurnal parallax and aberration; geometric, no refraction, observer height 0), heliocentric_true_ecliptic_of_date and barycentric_true_ecliptic_of_date (light-time-corrected astrometric place from the Sun's centre / the solar-system barycentre: no aberration, no gravitational deflection; target sampled at t minus light time, origin at t). The label names the frame that was computed; a response never claims one it did not use.",
          "title": "Coordinate Reference Frame"
        },
        "coordinate_system": {
          "anyOf": [
            {
              "$ref": "#/$defs/CoordinateSystemEnum"
            },
            {
              "type": "string"
            }
          ],
          "description": "Coordinate system the positions were computed in: geocentric, topocentric, heliocentric or barycentric.",
          "title": "Coordinate System"
        },
        "delta_t_seconds": {
          "anyOf": [
            {
              "type": "number"
            }
          ],
          "description": "Delta T (TT - UT1) applied during calculation, in seconds",
          "title": "Delta T Seconds"
        },
        "delta_t_source": {
          "anyOf": [
            {
              "$ref": "#/$defs/DeltaTSourceEnum"
            },
            {
              "type": "string"
            }
          ],
          "description": "Source of Delta T values (computation engine, IERS, approximation)",
          "title": "Delta T Source"
        },
        "ephemeris_source": {
          "anyOf": [
            {
              "type": "string"
            }
          ],
          "description": "Primary ephemeris source (e.g., SuperNOVAS / Calceph)",
          "title": "Ephemeris Source"
        },
        "ephemeris_version": {
          "anyOf": [
            {
              "type": "string"
            }
          ],
          "description": "Version of the ephemeris data files",
          "title": "Ephemeris Version"
        },
        "fixed_star_catalog": {
          "anyOf": [
            {
              "$ref": "#/$defs/FixedStarCatalogEnum"
            },
            {
              "type": "string"
            }
          ],
          "description": "Fixed star catalog or subset identifier",
          "title": "Fixed Star Catalog"
        },
        "house_system": {
          "anyOf": [
            {
              "$ref": "#/$defs/HouseSystemEnum"
            },
            {
              "type": "string"
            }
          ],
          "description": "House system actually used during calculation",
          "title": "House System"
        },
        "include_fixed_stars": {
          "anyOf": [
            {
              "type": "boolean"
            }
          ],
          "description": "Whether fixed stars were included",
          "title": "Include Fixed Stars"
        },
        "julian_day": {
          "anyOf": [
            {
              "format": "double",
              "type": "number"
            }
          ],
          "description": "Julian Day Number representing the calculation instant",
          "title": "Julian Day"
        },
        "lunar_nodes": {
          "additionalProperties": {
            "type": "object"
          },
          "description": "How each lunar node and apogee body in this response was computed, keyed by the body's name in the planets block (e.g. \"North Node (True)\"). Each entry carries `method` (`mean` or `true_osculating`) and `algorithm`; the true node also carries `frame` and `matches` (the Swiss Ephemeris equivalent), and a South Node carries `derived_from` and `offset`. Only bodies actually present in the response appear. Authoritative per body: when both nodes are returned, `node_source` alone cannot say which is which.",
          "title": "Lunar Nodes",
          "type": "object"
        },
        "missing_objects": {
          "anyOf": [
            {
              "additionalProperties": {
                "items": {
                  "type": "object"
                },
                "type": "array"
              },
              "type": "object"
            }
          ],
          "description": "Objects that could not be calculated along with reasons",
          "title": "Missing Objects"
        },
        "node_source": {
          "anyOf": [
            {
              "$ref": "#/$defs/NodeSourceEnum"
            },
            {
              "type": "string"
            }
          ],
          "description": "Lunar node/apsides mode in effect. Echoes `configuration.node_source` when the request sent one (it also selects the Lilith variant). Otherwise names the nodes the response carries: `mean`, `true_osculating`, or `mean_and_true_osculating` for the default roster, which returns both North Nodes. Omitted when the response carries no lunar node. See `lunar_nodes` for the per-body method.",
          "title": "Node Source"
        },
        "object_set": {
          "anyOf": [
            {
              "$ref": "#/$defs/ObjectSetEnum"
            },
            {
              "type": "string"
            }
          ],
          "description": "Named object set or preset powering the calculation",
          "title": "Object Set"
        },
        "orb_system_used": {
          "anyOf": [
            {
              "type": "string"
            }
          ],
          "description": "Aspect orb system applied",
          "title": "Orb System Used"
        },
        "precision_level": {
          "anyOf": [
            {
              "type": "string"
            }
          ],
          "description": "Legacy precision descriptor",
          "title": "Precision Level"
        },
        "precision_summary": {
          "$ref": "#/$defs/PrecisionSummary",
          "description": "Structured precision summary aligned with validation results"
        },
        "processing_time_ms": {
          "anyOf": [
            {
              "type": "number"
            }
          ],
          "description": "End-to-end processing time in milliseconds",
          "title": "Processing Time Ms"
        },
        "server_version": {
          "description": "Build identifier of the engine that produced this response. Moves on every deploy, so it is the signal for resolution-LOGIC changes — the class of change that can move a historical offset without touching overlay data (and therefore without moving tz_overlay_version). Poll both.",
          "title": "Server Version",
          "type": "string"
        },
        "sidereal_time": {
          "anyOf": [
            {
              "type": "number"
            }
          ],
          "description": "Local sidereal time in hours",
          "title": "Sidereal Time"
        },
        "technique_id": {
          "anyOf": [
            {
              "type": "string"
            }
          ],
          "description": "High-level technique identifier (e.g., natal, synastry, composite, overlay)",
          "title": "Technique Id"
        },
        "technique_label": {
          "anyOf": [
            {
              "type": "string"
            }
          ],
          "description": "Human-readable technique label",
          "title": "Technique Label"
        },
        "technique_method": {
          "anyOf": [
            {
              "type": "string"
            }
          ],
          "description": "Method name within a technique (e.g., davidson, midpoint)",
          "title": "Technique Method"
        },
        "technique_version": {
          "anyOf": [
            {
              "type": "string"
            }
          ],
          "description": "Technique implementation version (for future-proofing)",
          "title": "Technique Version"
        },
        "time_scale": {
          "anyOf": [
            {
              "$ref": "#/$defs/TimeScaleEnum"
            },
            {
              "type": "string"
            }
          ],
          "description": "Time scale used for internal calculations (UTC, TT, TDB)",
          "title": "Time Scale"
        },
        "tz_overlay_hash": {
          "description": "Content hash of the historical-correction overlay dataset that produced this answer. Stamped only when an overlay row applied (tz_rule_source starts with 'overlay:').",
          "title": "Tz Overlay Hash",
          "type": "string"
        },
        "tz_overlay_version": {
          "description": "Monotonic version of the historical-correction overlay dataset that produced this answer. Stamped only when an overlay row applied. Tracks overlay DATA only — pair with server_version to also catch resolution-logic changes.",
          "title": "Tz Overlay Version",
          "type": "integer"
        },
        "tz_precision": {
          "description": "Sourcing grade of the overlay row that produced the offset: 'statutory' (operative text of a session law or statute verified), 'documented' (contemporary reporting), or 'inferred' (deduced from legal context; verify before relying on it near the row's edges). Stamped only when an overlay row applied.",
          "enum": [
            "statutory",
            "documented",
            "inferred"
          ],
          "title": "Tz Precision",
          "type": "string"
        },
        "tz_rule_citation": {
          "description": "Primary-source citation for the overlay row that produced the offset — statute reference, ICC/agency order number, or documented press/almanac source. Stamped only when an overlay row applied.",
          "title": "Tz Rule Citation",
          "type": "string"
        },
        "zodiac_type": {
          "anyOf": [
            {
              "$ref": "#/$defs/ZodiacTypeEnum"
            },
            {
              "type": "string"
            }
          ],
          "description": "Zodiac framework applied (tropical/sidereal)",
          "title": "Zodiac Type"
        }
      },
      "title": "CalculationMetadata",
      "type": "object"
    },
    "ConjunctionEvent": {
      "description": "Details of a Venus-Sun conjunction event (Venus Star Point).",
      "properties": {
        "combust": {
          "description": "True if Venus is combust the Sun",
          "title": "Combust",
          "type": "boolean"
        },
        "conjunction_type": {
          "description": "Which kind of Sun-Venus conjunction this is. inferior: Venus passes between Earth and the Sun (Venus retrograde). superior: Venus passes behind the Sun (Venus direct). Found from the direction the geocentric elongation crosses zero.",
          "enum": [
            "inferior",
            "superior"
          ],
          "title": "Conjunction Type",
          "type": "string"
        },
        "decan": {
          "description": "Decan (1-3) of the zodiac sign",
          "title": "Decan",
          "type": "integer"
        },
        "element": {
          "description": "Zodiac element (Fire, Earth, Air, Water)",
          "title": "Element",
          "type": "string"
        },
        "exact": {
          "description": "True if orb is within the exact threshold (usually < 1 arc minute)",
          "title": "Exact",
          "type": "boolean"
        },
        "julian_day": {
          "description": "Julian Day of the exact conjunction",
          "format": "double",
          "title": "Julian Day",
          "type": "number"
        },
        "modality": {
          "description": "Zodiac modality (Cardinal, Fixed, Mutable)",
          "title": "Modality",
          "type": "string"
        },
        "orb": {
          "description": "Degree separation between Venus and Sun",
          "title": "Orb",
          "type": "number"
        },
        "planet_longitude": {
          "description": "Longitude of Venus at the time of conjunction",
          "title": "Planet Longitude",
          "type": "number"
        },
        "sign": {
          "description": "Zodiac sign name",
          "title": "Sign",
          "type": "string"
        },
        "star_longitude": {
          "description": "Longitude of the Star Point (Sun position)",
          "title": "Star Longitude",
          "type": "number"
        },
        "sun_dignity": {
          "description": "Sun's essential dignity at this position",
          "title": "Sun Dignity",
          "type": "string"
        },
        "timestamp": {
          "description": "ISO-8601 timestamp of the conjunction",
          "title": "Timestamp",
          "type": "string"
        },
        "under_beams": {
          "description": "True if Venus is under the Sun's beams",
          "title": "Under Beams",
          "type": "boolean"
        },
        "venus_dignity": {
          "description": "Venus's essential dignity at this position",
          "title": "Venus Dignity",
          "type": "string"
        },
        "visibility": {
          "description": "The phase Venus enters after this conjunction: morning_star after an inferior conjunction, evening_star after a superior one. (At the exact conjunction Venus is cazimi; that is implied by orb and exact.)",
          "enum": [
            "morning_star",
            "evening_star"
          ],
          "title": "Visibility",
          "type": "string"
        }
      },
      "required": [
        "star_longitude",
        "planet_longitude",
        "orb",
        "exact",
        "julian_day",
        "timestamp",
        "sign",
        "element",
        "modality",
        "decan",
        "venus_dignity",
        "sun_dignity",
        "visibility",
        "combust",
        "under_beams",
        "conjunction_type"
      ],
      "title": "ConjunctionEvent",
      "type": "object"
    },
    "CoordinateSystemEnum": {
      "description": "Coordinate system used for calculations.",
      "enum": [
        "geocentric",
        "topocentric",
        "heliocentric",
        "barycentric"
      ],
      "title": "CoordinateSystemEnum",
      "type": "string"
    },
    "DeltaTSourceEnum": {
      "description": "Source of ΔT values used in calculations.",
      "enum": [
        "nasa_jpl",
        "iers",
        "approximation_model"
      ],
      "title": "DeltaTSourceEnum",
      "type": "string"
    },
    "FixedStarCatalogEnum": {
      "description": "Fixed star catalog snapshots.",
      "enum": [
        "bright_mag3",
        "bright_mag5",
        "royal_stars",
        "parans_key"
      ],
      "title": "FixedStarCatalogEnum",
      "type": "string"
    },
    "HouseSystemEnum": {
      "description": "Supported house systems.",
      "enum": [
        "P",
        "K",
        "O",
        "R",
        "C",
        "E",
        "W"
      ],
      "title": "HouseSystemEnum",
      "type": "string"
    },
    "NodeSourceEnum": {
      "description": "Node/apsides calculation modes (SE §2.2).",
      "enum": [
        "true_osculating",
        "mean",
        "mean_apsides"
      ],
      "title": "NodeSourceEnum",
      "type": "string"
    },
    "ObjectSetEnum": {
      "description": "Standardized celestial object bundles.",
      "enum": [
        "traditional_7",
        "modern_10",
        "modern_plus_chiron",
        "asteroids_major",
        "full",
        "custom"
      ],
      "title": "ObjectSetEnum",
      "type": "string"
    },
    "PrecisionSummary": {
      "additionalProperties": true,
      "description": "Structured precision report for calculation metadata.",
      "properties": {
        "max_position_error_arcseconds": {
          "anyOf": [
            {
              "type": "number"
            }
          ],
          "description": "Maximum validated positional error in arcseconds",
          "title": "Max Position Error Arcseconds"
        },
        "max_timing_error_seconds": {
          "anyOf": [
            {
              "type": "number"
            }
          ],
          "description": "Maximum validated timing error in seconds",
          "title": "Max Timing Error Seconds"
        },
        "notes": {
          "anyOf": [
            {
              "type": "string"
            }
          ],
          "description": "Additional human-readable context for the precision summary",
          "title": "Notes"
        },
        "reference_profile": {
          "anyOf": [
            {
              "type": "string"
            }
          ],
          "description": "Reference dataset or validation profile used for the comparison",
          "title": "Reference Profile"
        }
      },
      "title": "PrecisionSummary",
      "type": "object"
    },
    "TimeScaleEnum": {
      "description": "Time scale used for reporting results.",
      "enum": [
        "UTC",
        "TT",
        "TDB"
      ],
      "title": "TimeScaleEnum",
      "type": "string"
    },
    "ZodiacTypeEnum": {
      "description": "Supported zodiac frameworks.",
      "enum": [
        "tropical",
        "sidereal"
      ],
      "title": "ZodiacTypeEnum",
      "type": "string"
    }
  }
}