Envelope

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/cyclecalcs/main/json-schema/cyclecalcs-envelope-schema.json",
  "title": "Envelope",
  "description": "The nine-key v2 response envelope. Every /v2 endpoint returns exactly these keys, in this order, on every 200 (spec-00 1.1).",
  "x-generated": "2026-09-28",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cyclecalcs-apsides-api-openapi.yml#/components/schemas/Envelope",
  "type": "object",
  "required": [
    "endpoint",
    "computed_at",
    "query",
    "data",
    "warnings",
    "links",
    "meta",
    "attribution",
    "docs"
  ],
  "properties": {
    "endpoint": {
      "type": "string",
      "description": "The endpoint path that produced this response."
    },
    "computed_at": {
      "type": "string",
      "format": "date-time",
      "description": "A revision stamp, never a wall clock: identical requests return identical bytes, so a fixed_instant or reference response can be cached for a year and 304 stays reachable."
    },
    "query": {
      "type": "object",
      "description": "The request as understood: every resolved input (instant, location, presentation options) plus `ignored`, in the order spec-00 13.2 defines. Shape is endpoint-specific.",
      "additionalProperties": true
    },
    "data": {
      "description": "The answer. Shape is endpoint-specific; see each operation's summary and /api/reference.html."
    },
    "warnings": {
      "type": "array",
      "description": "Machine-readable notices about this response. Empty when none apply; never changes the HTTP status.",
      "items": {
        "$ref": "#/$defs/Warning"
      }
    },
    "links": {
      "type": "object",
      "description": "Related URLs. self reproduces this exact response; docs is always present; others (page, spec, next, first, explain) appear where relevant.",
      "additionalProperties": {
        "type": "string",
        "format": "uri"
      }
    },
    "meta": {
      "type": "object",
      "description": "Provenance: engine version, rights and attribution, cache class, accuracy statement, tzdb version, and endpoint-specific conventions (refraction model, horizon definitions, time scales, and so on). Never subject to `fields` projection.",
      "additionalProperties": true
    },
    "attribution": {
      "type": "string",
      "description": "The credit line, byte-identical to meta.attribution.text."
    },
    "docs": {
      "type": "string",
      "format": "uri",
      "description": "The human-readable reference section for this endpoint."
    }
  },
  "$defs": {
    "Warning": {
      "type": "object",
      "description": "One machine-readable notice. Exactly four keys, in this order (spec-00 11.4). Never changes the HTTP status.",
      "required": [
        "code",
        "message",
        "field",
        "value"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "ambiguous_local_time",
            "antipodal_pair_not_aspected",
            "approximates_undefined_placidus",
            "assumed_utc",
            "birth_time_unknown",
            "blocked_layer_omitted",
            "cusps_not_monotonic",
            "dataset_stale",
            "decorative_starfield",
            "dms_rounds_to_next_sign",
            "dst_discontinuity",
            "duplicate_alarm",
            "duplicate_aspect",
            "duplicate_body",
            "duplicate_depression",
            "duplicate_derived",
            "duplicate_house_system",
            "duplicate_include",
            "duplicate_pair",
            "duplicate_parameter",
            "duplicate_point",
            "duplicate_shower",
            "duplicate_source",
            "elevation_ignored",
            "estimate_only",
            "extrapolated_epoch",
            "field_blocked",
            "fields_ignored",
            "harmonic_orb_mode_has_no_effect",
            "high_latitude_caution",
            "horizon_overridden",
            "house_system_substituted",
            "large_intercept",
            "lot_term_null",
            "low_altitude_precision",
            "mean_node_model",
            "model_disagreement",
            "model_epoch_only",
            "moon_dominates",
            "no_astronomical_darkness",
            "no_location_orientation",
            "no_search_result",
            "nonexistent_local_time_shifted",
            "not_visible_from_location",
            "oblateness_simplified",
            "orbit_arc_truncated",
            "parameter_ignored",
            "perfection_search_truncated",
            "place_ambiguous",
            "place_index_tier_2",
            "place_matched_by_substring",
            "placement_within_error_of_boundary",
            "polar_angles_flipped",
            "polar_day",
            "polar_night",
            "polar_region",
            "prose_window_differs",
            "refraction_below_cutoff",
            "render_degenerate",
            "rounded_parameter",
            "sect_tests_disagree",
            "shape_ignored",
            "source_window_clipped",
            "station_near_window_edge",
            "station_search_truncated",
            "time_format_not_applicable",
            "time_scale_undefined",
            "timezone_from_place",
            "truncated_results",
            "tz_source_boundary_1970",
            "tzdb_lmt_interval",
            "unknown_parameter",
            "unusual_navigational_body",
            "vertex_undefined_at_equator"
          ],
          "description": "A stable, lower_snake_case token. The full registry is at GET /v2/enums?set=warning_codes."
        },
        "message": {
          "type": "string",
          "description": "A human-readable explanation. Not parsed by machines; use `code`."
        },
        "field": {
          "type": [
            "string",
            "null"
          ],
          "description": "The data or query pointer the warning is about, dot-addressed the same way `fields` is. Null when the warning is not about one field."
        },
        "value": {
          "description": "The value involved, when there is a single obvious one to show. Null otherwise."
        }
      }
    }
  }
}