pipeline-input.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/sakobu/rpo-toolkit/docs/schema/pipeline-input.schema.json",
  "title": "PipelineInput",
  "description": "Canonical mission input for the RPO planner. Used by the CLI (as JSON file input for mission, validate, and mc commands). The WebSocket API uses the same domain types (StateVector, SpacecraftConfig, WaypointMission, etc.) but each message carries only the fields it needs rather than wrapping a full PipelineInput.",
  "type": "object",
  "required": ["chief", "deputy", "waypoints"],
  "properties": {
    "chief": {
      "$ref": "#/$defs/StateVector",
      "description": "Chief spacecraft ECI state at the mission epoch."
    },
    "deputy": {
      "$ref": "#/$defs/StateVector",
      "description": "Deputy spacecraft ECI state at the mission epoch."
    },
    "perch": {
      "$ref": "#/$defs/PerchGeometry",
      "description": "Perch orbit geometry for Lambert-to-proximity handoff. Default: V-bar hold at 5 km.",
      "default": { "v_bar": { "along_track_km": 5.0 } }
    },
    "lambert_tof_s": {
      "type": "number",
      "description": "Lambert transfer time-of-flight in seconds.",
      "default": 3600.0,
      "exclusiveMinimum": 0
    },
    "lambert_config": {
      "$ref": "#/$defs/LambertConfig",
      "description": "Lambert solver configuration (direction and revolution count).",
      "default": { "direction": "auto", "revolutions": 0 }
    },
    "waypoints": {
      "type": "array",
      "description": "Waypoint targets in the RIC frame. At least one waypoint is required for mission planning.",
      "items": {
        "$ref": "#/$defs/WaypointInput"
      }
    },
    "proximity": {
      "$ref": "#/$defs/ProximityConfig",
      "description": "Classification threshold for proximity vs. far-field.",
      "default": { "roe_threshold": 0.005 }
    },
    "config": {
      "$ref": "#/$defs/MissionConfig",
      "description": "Solver configuration: targeting, TOF optimization, and safety."
    },
    "propagator": {
      "$ref": "#/$defs/PropagatorChoice",
      "description": "Propagator selection: J2 analytical or J2+drag analytical.",
      "default": "j2"
    },
    "chief_config": {
      "$ref": "#/$defs/SpacecraftChoice",
      "description": "Chief spacecraft selection: named preset or custom properties. Required for validate, mc, and drag extraction."
    },
    "deputy_config": {
      "$ref": "#/$defs/SpacecraftChoice",
      "description": "Deputy spacecraft selection: named preset or custom properties. Required for validate, mc, and drag extraction."
    },
    "navigation_accuracy": {
      "$ref": "#/$defs/NavigationAccuracy",
      "description": "Navigation accuracy for covariance propagation. If omitted, covariance is not computed."
    },
    "maneuver_uncertainty": {
      "$ref": "#/$defs/ManeuverUncertainty",
      "description": "Maneuver execution uncertainty for covariance propagation."
    },
    "monte_carlo": {
      "$ref": "#/$defs/MonteCarloConfig",
      "description": "Monte Carlo configuration. Required for the RunMC command."
    },
    "cola": {
      "$ref": "#/$defs/ColaConfig",
      "description": "Collision avoidance configuration. If omitted, COLA auto-computes when config.safety is present and POCA violations exist (using min_distance_3d_km as target, 10 m/s budget). Explicit config overrides auto-derived values."
    },
    "safety_requirements": {
      "$ref": "#/$defs/SafetyRequirements",
      "description": "Safety requirements for formation design enrichment. When set, an enriched plan with safe e/i vectors is computed alongside the baseline plan, and waypoint enrichment + transit safety are computed (advisory)."
    }
  },
  "additionalProperties": false,
  "$defs": {
    "StateVector": {
      "type": "object",
      "description": "Spacecraft state in Earth-Centered Inertial (ECI) frame.",
      "required": ["epoch", "position_eci_km", "velocity_eci_km_s"],
      "properties": {
        "epoch": {
          "type": "string",
          "description": "Epoch in ISO 8601 format (e.g., \"2024-01-01T00:00:00 UTC\"). Parsed by hifitime.",
          "examples": ["2024-01-01T00:00:00 UTC"]
        },
        "position_eci_km": {
          "type": "array",
          "description": "ECI position vector [x, y, z] in kilometers.",
          "items": { "type": "number" },
          "minItems": 3,
          "maxItems": 3
        },
        "velocity_eci_km_s": {
          "type": "array",
          "description": "ECI velocity vector [vx, vy, vz] in km/s.",
          "items": { "type": "number" },
          "minItems": 3,
          "maxItems": 3
        }
      },
      "additionalProperties": false
    },
    "WaypointInput": {
      "type": "object",
      "description": "A waypoint target in the RIC (Radial, In-track, Cross-track) frame relative to the chief.",
      "required": ["position_ric_km"],
      "properties": {
        "position_ric_km": {
          "type": "array",
          "description": "RIC position target [R, I, C] in kilometers.",
          "items": { "type": "number" },
          "minItems": 3,
          "maxItems": 3
        },
        "velocity_ric_km_s": {
          "type": "array",
          "description": "RIC velocity target [R, I, C] in km/s. If omitted, the waypoint is position-only: targeting derives the minimum-norm (cheapest Δv) arrival velocity analytically, and formation enrichment has 3-DOF null-space freedom to propose a safe e/i-aligned alternative. Use [0, 0, 0] for explicit station-keeping (zero-velocity hold). If set to any value, the waypoint is velocity-constrained: targeting hits the exact (position, velocity) pair, and enrichment is advisory-only.",
          "items": { "type": "number" },
          "minItems": 3,
          "maxItems": 3
        },
        "tof_s": {
          "type": "number",
          "description": "Time-of-flight hint in seconds. If omitted, the solver optimizes TOF via golden-section search.",
          "exclusiveMinimum": 0
        },
        "label": {
          "type": "string",
          "description": "Human-readable label for display (e.g., \"Approach to 2 km\")."
        }
      },
      "additionalProperties": false
    },
    "PerchGeometry": {
      "description": "Predefined perch orbit geometry relative to the chief. Exactly one variant must be specified.",
      "oneOf": [
        {
          "type": "object",
          "description": "V-bar hold: deputy ahead/behind chief along the velocity vector.",
          "required": ["v_bar"],
          "properties": {
            "v_bar": {
              "type": "object",
              "required": ["along_track_km"],
              "properties": {
                "along_track_km": {
                  "type": "number",
                  "description": "Along-track offset in km. Positive = ahead of chief."
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "description": "R-bar hold: deputy above/below chief along the radial vector.",
          "required": ["r_bar"],
          "properties": {
            "r_bar": {
              "type": "object",
              "required": ["radial_km"],
              "properties": {
                "radial_km": {
                  "type": "number",
                  "description": "Radial offset in km. Positive = above chief."
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "description": "Custom ROE state for advanced perch geometries. Specifies an arbitrary quasi-nonsingular ROE vector directly.",
          "required": ["custom"],
          "properties": {
            "custom": {
              "$ref": "#/$defs/QuasiNonsingularROE"
            }
          },
          "additionalProperties": false
        }
      ]
    },
    "QuasiNonsingularROE": {
      "type": "object",
      "description": "Quasi-nonsingular relative orbital elements (Koenig Eq. 2 / D'Amico Eq. 2.2). All elements are dimensionless, normalized by chief semi-major axis.",
      "required": ["da", "dlambda", "dex", "dey", "dix", "diy"],
      "properties": {
        "da": {
          "type": "number",
          "description": "Relative semi-major axis: (a_d - a_c) / a_c."
        },
        "dlambda": {
          "type": "number",
          "description": "Relative mean longitude."
        },
        "dex": {
          "type": "number",
          "description": "Relative eccentricity vector x-component."
        },
        "dey": {
          "type": "number",
          "description": "Relative eccentricity vector y-component."
        },
        "dix": {
          "type": "number",
          "description": "Relative inclination vector x-component."
        },
        "diy": {
          "type": "number",
          "description": "Relative inclination vector y-component."
        }
      },
      "additionalProperties": false
    },
    "LambertConfig": {
      "type": "object",
      "description": "Configuration for the in-tree Izzo Lambert transfer solver. Single code path at all revolution counts: 0 = direct transfer, N >= 1 = the long-period (low-energy) branch of the M=N family. The `direction` field is honored at every revolution count; `auto` evaluates short-way and long-way and returns the lower-Δv branch.",
      "properties": {
        "direction": {
          "type": "string",
          "description": "Transfer direction selection. `auto` returns the lower-Δv of short-way and long-way (recommended for interactive use). Honored at all revolution counts.",
          "enum": ["auto", "short_way", "long_way"],
          "default": "auto"
        },
        "revolutions": {
          "type": "integer",
          "description": "Number of complete revolutions (0 = direct transfer; N >= 1 = long-period branch of the M=N multi-revolution family).",
          "minimum": 0,
          "maximum": 255,
          "default": 0
        }
      },
      "additionalProperties": false
    },
    "ProximityConfig": {
      "type": "object",
      "description": "Classification threshold configuration.",
      "properties": {
        "roe_threshold": {
          "type": "number",
          "description": "Max dimensionless relative separation (delta-r/r) for ROE linearization validity. Below this threshold, the pair is classified as Proximity; above, as FarField.",
          "default": 0.005,
          "exclusiveMinimum": 0
        }
      },
      "additionalProperties": false
    },
    "MissionConfig": {
      "type": "object",
      "description": "Bundled mission configuration: targeting, TOF optimization, and safety.",
      "properties": {
        "targeting": {
          "$ref": "#/$defs/TargetingConfig",
          "description": "Newton-Raphson targeting solver settings."
        },
        "tof": {
          "$ref": "#/$defs/TofOptConfig",
          "description": "Time-of-flight optimization settings."
        },
        "safety": {
          "$ref": "#/$defs/SafetyConfig",
          "description": "Passive safety analysis settings. If omitted, safety analysis is skipped."
        }
      },
      "additionalProperties": false
    },
    "TargetingConfig": {
      "type": "object",
      "description": "Newton-Raphson targeting solver configuration.",
      "properties": {
        "max_iterations": {
          "type": "integer",
          "description": "Maximum Newton-Raphson iterations.",
          "default": 100,
          "minimum": 1
        },
        "position_tol_km": {
          "type": "number",
          "description": "Position convergence tolerance in km.",
          "default": 1e-6,
          "exclusiveMinimum": 0
        },
        "initial_damping": {
          "type": "number",
          "description": "Initial damping factor for Newton steps.",
          "default": 1.0,
          "exclusiveMinimum": 0
        },
        "dv_cap_km_s": {
          "type": "number",
          "description": "Cap on any single delta-v component in km/s.",
          "default": 1.0,
          "exclusiveMinimum": 0
        },
        "trajectory_steps": {
          "type": "integer",
          "description": "Number of trajectory sample points per leg for output.",
          "default": 200,
          "minimum": 1
        }
      },
      "additionalProperties": false
    },
    "TofOptConfig": {
      "type": "object",
      "description": "Time-of-flight optimization via golden-section search.",
      "properties": {
        "min_periods": {
          "type": "number",
          "description": "Minimum TOF as fraction of the chief orbital period.",
          "default": 0.5,
          "exclusiveMinimum": 0
        },
        "max_periods": {
          "type": "number",
          "description": "Maximum TOF as fraction of the chief orbital period.",
          "default": 3.0,
          "exclusiveMinimum": 0
        },
        "num_starts": {
          "type": "integer",
          "description": "Number of initial TOF samples for multi-start optimization.",
          "default": 5,
          "minimum": 1
        },
        "tol_s": {
          "type": "number",
          "description": "Golden-section convergence tolerance in seconds.",
          "default": 1.0,
          "exclusiveMinimum": 0
        }
      },
      "additionalProperties": false
    },
    "SafetyConfig": {
      "type": "object",
      "description": "Safety analysis thresholds for operational and passive safety checks.",
      "properties": {
        "min_ei_separation_km": {
          "type": "number",
          "description": "Eccentricity/inclination vector separation threshold in km (passive/abort safety, D'Amico Eq. 2.22).",
          "default": 0.2,
          "exclusiveMinimum": 0
        },
        "min_distance_3d_km": {
          "type": "number",
          "description": "3D keep-out sphere threshold in km (operational safety).",
          "default": 0.1,
          "exclusiveMinimum": 0
        }
      },
      "additionalProperties": false
    },
    "PropagatorChoice": {
      "description": "Propagator selection. Either the string \"j2\" or an object with a \"j2_drag\" key containing a DragConfig.",
      "oneOf": [
        {
          "const": "j2",
          "description": "J2-perturbed analytical propagation (no drag)."
        },
        {
          "type": "object",
          "description": "J2 + differential drag analytical propagation.",
          "required": ["j2_drag"],
          "properties": {
            "j2_drag": {
              "type": "object",
              "required": ["drag"],
              "properties": {
                "drag": {
                  "$ref": "#/$defs/DragConfig"
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        }
      ]
    },
    "DragConfig": {
      "type": "object",
      "description": "Density-model-free (DMF) differential drag configuration (Koenig Sec. VIII). Time derivatives of relative orbital elements due to differential drag.",
      "required": ["da_dot", "dex_dot", "dey_dot"],
      "properties": {
        "da_dot": {
          "type": "number",
          "description": "Time derivative of relative SMA due to drag (1/s, normalized by chief SMA)."
        },
        "dex_dot": {
          "type": "number",
          "description": "Time derivative of relative eccentricity x-component due to drag (1/s)."
        },
        "dey_dot": {
          "type": "number",
          "description": "Time derivative of relative eccentricity y-component due to drag (1/s)."
        }
      },
      "additionalProperties": false
    },
    "ColaConfig": {
      "type": "object",
      "description": "Collision avoidance (COLA) maneuver design configuration. When a Brent-refined POCA distance falls below target_distance_km, the solver computes the minimum-fuel impulsive correction to push closest approach beyond the target.",
      "required": ["target_distance_km", "max_dv_km_s"],
      "properties": {
        "target_distance_km": {
          "type": "number",
          "description": "Target POCA distance after avoidance maneuver in km.",
          "exclusiveMinimum": 0
        },
        "max_dv_km_s": {
          "type": "number",
          "description": "Maximum available delta-v budget for avoidance in km/s.",
          "exclusiveMinimum": 0
        }
      },
      "additionalProperties": false
    },
    "SafetyRequirements": {
      "type": "object",
      "description": "Safety requirements for formation design enrichment (D'Amico Eq. 2.22). Controls perch e/i vector enrichment and transit safety analysis.",
      "required": ["min_separation_km"],
      "properties": {
        "min_separation_km": {
          "type": "number",
          "description": "Minimum R/C separation in km. Maps to d_min in D'Amico Eq. 2.22.",
          "exclusiveMinimum": 0
        },
        "alignment": {
          "$ref": "#/$defs/EiAlignment",
          "description": "E/I vector alignment strategy. Defaults to \"parallel\" if omitted.",
          "default": "parallel"
        }
      },
      "additionalProperties": false
    },
    "EiAlignment": {
      "description": "E/I vector alignment strategy for formation design. Both parallel and anti-parallel maximize the passive safety metric (D'Amico Eq. 2.23).",
      "type": "string",
      "enum": ["parallel", "anti_parallel", "auto"],
      "default": "parallel"
    },
    "SpacecraftChoice": {
      "description": "Spacecraft configuration: a named preset or custom properties.",
      "oneOf": [
        {
          "const": "cubesat_6u",
          "description": "Typical 6U cubesat: 12 kg, 0.06 m², Cd=2.2, Cr=1.5."
        },
        {
          "const": "servicer_500kg",
          "description": "Typical 500 kg servicer: 500 kg, 1.0 m², Cd=2.2, Cr=1.5."
        },
        {
          "type": "object",
          "description": "Custom spacecraft physical properties.",
          "required": ["custom"],
          "properties": {
            "custom": {
              "$ref": "#/$defs/SpacecraftConfig"
            }
          },
          "additionalProperties": false
        }
      ]
    },
    "SpacecraftConfig": {
      "type": "object",
      "description": "Physical properties of a spacecraft for force modeling (nyx propagation, drag extraction).",
      "required": [
        "dry_mass_kg",
        "drag_area_m2",
        "coeff_drag",
        "srp_area_m2",
        "coeff_reflectivity"
      ],
      "properties": {
        "dry_mass_kg": {
          "type": "number",
          "description": "Spacecraft dry mass in kg.",
          "exclusiveMinimum": 0
        },
        "drag_area_m2": {
          "type": "number",
          "description": "Drag reference area in square meters.",
          "exclusiveMinimum": 0
        },
        "coeff_drag": {
          "type": "number",
          "description": "Coefficient of drag (dimensionless, typically 2.0-2.5).",
          "exclusiveMinimum": 0
        },
        "srp_area_m2": {
          "type": "number",
          "description": "Solar radiation pressure reference area in square meters.",
          "exclusiveMinimum": 0
        },
        "coeff_reflectivity": {
          "type": "number",
          "description": "Coefficient of reflectivity (dimensionless, typically 1.0-2.0).",
          "exclusiveMinimum": 0
        }
      },
      "additionalProperties": false
    },
    "NavigationAccuracy": {
      "type": "object",
      "description": "Navigation accuracy specification in the RIC frame for covariance propagation.",
      "required": ["position_sigma_ric_km", "velocity_sigma_ric_km_s"],
      "properties": {
        "position_sigma_ric_km": {
          "type": "array",
          "description": "1-sigma position accuracy per RIC axis [radial, in-track, cross-track] in km.",
          "items": { "type": "number", "exclusiveMinimum": 0 },
          "minItems": 3,
          "maxItems": 3
        },
        "velocity_sigma_ric_km_s": {
          "type": "array",
          "description": "1-sigma velocity accuracy per RIC axis [radial, in-track, cross-track] in km/s.",
          "items": { "type": "number", "exclusiveMinimum": 0 },
          "minItems": 3,
          "maxItems": 3
        }
      },
      "additionalProperties": false
    },
    "ManeuverUncertainty": {
      "type": "object",
      "description": "Maneuver execution uncertainty model for covariance propagation.",
      "required": ["magnitude_sigma", "pointing_sigma_rad"],
      "properties": {
        "magnitude_sigma": {
          "type": "number",
          "description": "Proportional 1-sigma magnitude error (dimensionless, e.g., 0.01 = 1%).",
          "minimum": 0
        },
        "pointing_sigma_rad": {
          "type": "number",
          "description": "1-sigma pointing error in radians, applied as isotropic rotation about the delta-v axis.",
          "minimum": 0
        }
      },
      "additionalProperties": false
    },
    "MonteCarloConfig": {
      "type": "object",
      "description": "Monte Carlo ensemble analysis configuration. All MC runs use nyx full-physics propagation.",
      "required": ["num_samples", "dispersions", "mode", "trajectory_steps"],
      "properties": {
        "num_samples": {
          "type": "integer",
          "description": "Number of Monte Carlo samples to run.",
          "minimum": 1
        },
        "dispersions": {
          "$ref": "#/$defs/DispersionConfig",
          "description": "Dispersion models for state, maneuver, and spacecraft properties."
        },
        "mode": {
          "type": "string",
          "description": "Execution mode: \"OpenLoop\" applies nominal delta-v plan with execution errors; \"ClosedLoop\" re-targets from each dispersed initial state.",
          "enum": ["open_loop", "closed_loop"],
          "default": "open_loop"
        },
        "seed": {
          "type": "integer",
          "description": "Master RNG seed for deterministic reproducibility. Defaults to 42 if omitted.",
          "minimum": 0
        },
        "trajectory_steps": {
          "type": "integer",
          "description": "Number of trajectory sample points per leg for dispersion envelope.",
          "minimum": 1
        }
      },
      "additionalProperties": false
    },
    "DispersionConfig": {
      "type": "object",
      "description": "Composite dispersion configuration for Monte Carlo analysis.",
      "properties": {
        "state": {
          "$ref": "#/$defs/StateDispersion",
          "description": "Initial state uncertainty in the RIC frame (applied to deputy)."
        },
        "maneuver": {
          "$ref": "#/$defs/ManeuverDispersion",
          "description": "Maneuver execution uncertainty."
        },
        "spacecraft": {
          "$ref": "#/$defs/SpacecraftDispersion",
          "description": "Spacecraft property uncertainty (deputy only)."
        }
      },
      "additionalProperties": false
    },
    "StateDispersion": {
      "type": "object",
      "description": "Initial state uncertainty model in the RIC frame, applied to the deputy.",
      "required": [
        "position_radial_km",
        "position_intrack_km",
        "position_crosstrack_km",
        "velocity_radial_km_s",
        "velocity_intrack_km_s",
        "velocity_crosstrack_km_s"
      ],
      "properties": {
        "position_radial_km": {
          "$ref": "#/$defs/Distribution",
          "description": "1-sigma radial position dispersion in km."
        },
        "position_intrack_km": {
          "$ref": "#/$defs/Distribution",
          "description": "1-sigma in-track position dispersion in km."
        },
        "position_crosstrack_km": {
          "$ref": "#/$defs/Distribution",
          "description": "1-sigma cross-track position dispersion in km."
        },
        "velocity_radial_km_s": {
          "$ref": "#/$defs/Distribution",
          "description": "1-sigma radial velocity dispersion in km/s."
        },
        "velocity_intrack_km_s": {
          "$ref": "#/$defs/Distribution",
          "description": "1-sigma in-track velocity dispersion in km/s."
        },
        "velocity_crosstrack_km_s": {
          "$ref": "#/$defs/Distribution",
          "description": "1-sigma cross-track velocity dispersion in km/s."
        }
      },
      "additionalProperties": false
    },
    "ManeuverDispersion": {
      "type": "object",
      "description": "Maneuver execution error model for Monte Carlo sampling.",
      "required": ["magnitude_sigma", "pointing_sigma_rad"],
      "properties": {
        "magnitude_sigma": {
          "type": "number",
          "description": "Proportional 1-sigma magnitude error (dimensionless, e.g., 0.01 = 1%).",
          "minimum": 0
        },
        "pointing_sigma_rad": {
          "type": "number",
          "description": "1-sigma pointing error in radians.",
          "minimum": 0
        }
      },
      "additionalProperties": false
    },
    "SpacecraftDispersion": {
      "type": "object",
      "description": "Spacecraft property uncertainty for Monte Carlo (deputy only).",
      "required": ["coeff_drag", "drag_area_m2", "dry_mass_kg"],
      "properties": {
        "coeff_drag": {
          "$ref": "#/$defs/Distribution",
          "description": "Drag coefficient dispersion."
        },
        "drag_area_m2": {
          "$ref": "#/$defs/Distribution",
          "description": "Drag cross-sectional area dispersion in square meters."
        },
        "dry_mass_kg": {
          "$ref": "#/$defs/Distribution",
          "description": "Dry mass dispersion in kg."
        }
      },
      "additionalProperties": false
    },
    "Distribution": {
      "description": "Distribution model for scalar uncertainty parameters. Exactly one variant.",
      "oneOf": [
        {
          "type": "object",
          "description": "Gaussian (normal) distribution.",
          "required": ["gaussian"],
          "properties": {
            "gaussian": {
              "type": "object",
              "required": ["sigma"],
              "properties": {
                "sigma": {
                  "type": "number",
                  "description": "1-sigma standard deviation (must be non-negative).",
                  "minimum": 0
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "description": "Uniform distribution centered on nominal.",
          "required": ["uniform"],
          "properties": {
            "uniform": {
              "type": "object",
              "required": ["half_width"],
              "properties": {
                "half_width": {
                  "type": "number",
                  "description": "Half-width of the uniform range (must be non-negative).",
                  "minimum": 0
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        }
      ]
    }
  }
}