Constellation JSON

What it is

The design document. Every command that generates or imports a constellation writes one, and every analysis command reads one.

It describes where satellites start, not where they go. Advancing them through time is propagation.

A complete document


{
  "schema_version": "orbitforge.constellation.v1",
  "name": "fmt",
  "description": "Walker delta 4/2/1 at 550 km, 53 deg inclination",
  "shells": [
    {
      "id": "s0",
      "name": "fmt shell",
      "altitude_km": 550.0,
      "inclination_deg": 53.0,
      "planes": 2,
      "satellites_per_plane": 2,
      "phasing": 1,
      "fov_deg": 45.0
    }
  ],
  "satellites": [
    {
      "id": "fmt-s0-p00-sat00",
      "name": "fmt-s0-p00-sat00",
      "shell_id": "s0",
      "plane_index": 0,
      "satellite_index": 0,
      "initial_orbit": {
        "semi_major_axis_km": 6928.137,
        "eccentricity": 0.0,
        "inclination_deg": 53.0,
        "raan_deg": 0.0,
        "argument_of_perigee_deg": 0.0,
        "true_anomaly_deg": 0.0
      },
      "payload": {
        "name": "fmt payload",
        "fov_deg": 45.0,
        "payload_type": "optical"
      }
    }
  ]
}

Real output, elided after the first satellite.

Top level

Parameter	Type	Unit	Default	Required	Description
`schema_version`	string	n/a	—	Yes	Format identifier, `orbitforge.constellation.v1`. Check it before parsing.
`name`	string	n/a	—	Yes	Constellation name. Becomes the identifier prefix on every satellite.
`description`	string	n/a	—	No	Generated summary, for example the Walker notation and geometry.
`shells`	array	n/a	—	Yes	Groups of planes sharing an altitude and inclination.
`satellites`	array	n/a	—	Yes	Every satellite, expanded. This is the authoritative list.

shells and satellites are not alternatives. The shell block records the parameters the constellation was generated from; the satellite list is the expansion and is what the analysis actually reads.

Editing a shell parameter by hand does not move the satellites. To change the geometry, regenerate.

Satellites

Parameter	Type	Unit	Default	Required	Description
`id`	string	n/a	—	No	Stable identifier, `<name>-s<shell>-p<plane>-sat<index>`. Error messages name satellites this way.
`shell_id`	string	n/a	—	No	Which shell this satellite belongs to.
`plane_index`	integer	index	—	No	Zero-based plane number.
`satellite_index`	integer	index	—	No	Zero-based position within the plane.
`initial_orbit`	object	n/a	—	No	Keplerian elements at the scenario epoch.
`payload`	object	n/a	—	No	Field of view and payload type, used for coverage footprints.

The identifier structure is worth knowing because diagnostics use it. A failure naming fmt-s0-p00-sat00 tells you the shell, plane, and slot without any lookup.

Initial orbit

Field	Unit	Note
`semi_major_axis_km`	km	From the Earth’s center, not altitude. 6928.137 is 550 km altitude
`eccentricity`	dimensionless	Zero for a generated circular shell
`inclination_deg`	deg
`raan_deg`	deg	Which plane, by equator crossing
`argument_of_perigee_deg`	deg	Undefined for a circular orbit; written as zero
`true_anomaly_deg`	deg	Position around the ring

semi_major_axis_km is measured from the Earth’s center, while the generator’s --altitude-km flag is measured from the surface. 550 km altitude becomes 6928.137 km semi-major axis.

Hand-editing this field with an altitude value places the satellite deep inside the Earth, and the propagator will happily integrate it.

Where it comes from

Producer	Notes
`constellation walker`	Generated geometry
`import-tle`	Real objects; satellites also carry their source TLE
`import-ephem`	Real objects; satellites also carry an ephemeris table
`design`	The recommended constellation from a synthesis run

Imported satellites carry extra data beyond what is shown above, and that extra data is what makes --model sgp4 or --model ephemeris available. A hand-written document has neither, so only the analytic and numerical models apply to it.

Hand-editing

The format is plain JSON and can be edited, with two cautions.

Editing a shell parameter changes only the record of how the constellation was generated. Editing initial_orbit on a satellite does move it, and nothing validates that the result is consistent with its shell, so a satellite can end up in a plane it does not belong to.

Regenerating is safer than editing whenever the geometry itself is what you want to change.