{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/openephemeris-com/json-schema/openephemeris-com-venus-star-points-response-schema.json",
  "title": "VenusStarPointsResponse",
  "description": "Success response containing Venus Star Points and metadata.",
  "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/VenusStarPointsResponse",
  "properties": {
    "calculation_metadata": {
      "allOf": [
        {
          "$ref": "#/$defs/CalculationMetadata"
        }
      ],
      "description": "Execution timing and precision metadata"
    },
    "natal_conjunction": {
      "allOf": [
        {
          "$ref": "#/$defs/ConjunctionEvent"
        }
      ],
      "description": "The last Sun-Venus conjunction strictly before the birth instant, inferior or superior. This is the natal point in Arielle Guttman's Venus Star Point technique (charted from the conjunction prior to birth, not the nearest one). Its visibility gives the Morning Star / Evening Star reading.",
      "title": "Natal Conjunction"
    },
    "star_points": {
      "description": "The five Sun-Venus conjunctions nearest in time to birth (not a fixed before/after split). For the natal point use natal_conjunction.",
      "items": {
        "$ref": "#/$defs/ConjunctionEvent"
      },
      "title": "Star Points",
      "type": "array"
    },
    "success": {
      "default": true,
      "description": "Status of the calculation",
      "title": "Success",
      "type": "boolean"
    }
  },
  "required": [
    "star_points",
    "calculation_metadata",
    "natal_conjunction"
  ],
  "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"
    }
  }
}