AstroPlan: a small, portable schedule format for astronomy apps.

Why this exists

A common plan file lets astronomy apps cooperate.

Many planning apps can identify good targets, many telescope apps can execute a plan, and many observers move between both. AstroPlan is intentionally modest: it names the targets, carries coordinates, preserves ordering, and optionally includes schedule timing. That is enough for an app to import a useful observing plan without understanding every private feature of the app that created it.

Supporting materials

The public repository is the implementation toolkit.

The AstroPlan GitHub repository contains the complete draft specification and machine-readable JSON Schema, along with registered extension definitions. It also includes real application exports, valid and deliberately invalid conformance fixtures, and a validator that developers can use while building import and export support.

Supporting materials include implementation prompts for Swift, Python, TypeScript, and Kotlin, plus an installable AstroPlan skill that can read, create, edit, and validate plan files. Contributions are welcome through issues and pull requests; the repository's contribution guide describes the compatibility and data-safety expectations for proposed changes.

License and adoption

AstroPlan is open for independent implementation.

AstroPlan is an open draft standard. The specification, schemas, examples, validator, implementation prompts, and skill in the public repository are available under the MIT License . Developers may implement AstroPlan in commercial or noncommercial applications without requesting permission from AstroGuide.

Applications that support AstroPlan remain independent implementations; compatibility does not imply affiliation with or endorsement by AstroGuide. Copies or substantial portions of repository materials should retain the included copyright and license notice.

Container

File format

• Extension: .astroplan
• Encoding: UTF-8 JSON
• Root object: one AstroPlan payload object
• Coordinates: equatorial J2000, preferably decimal fields plus display strings
• Dates: ISO 8601 timestamps with timezone offsets or Z
• Recommended MIME type: application/vnd.astroplan+json

AstroGuide currently registers .astroplan as an Apple file document type and imports files by extension. Other apps can use the extension, JSON payload, and MIME recommendation independently of Apple platform identifiers.

Payload shape

Top-level fields

scheduleContext

The schedule context describes the shared observing window. Apps that only exchange target lists can omit it.

target fields

A target should include a stable catalog identifier and, whenever possible, both machine-readable decimal coordinates and human-readable coordinate strings.

Every array occurrence is a separate schedule entry. Several entries may refer to the same catalog subject, and editors should use entryId when stable occurrence identity matters.

Schedule rules

Timing and ordering

• The order of targets preserves the author application's presentation order.
• When timing is present, offsets or timestamps determine chronological execution order.
• Repeated catalog subjects and overlapping entries are valid and must not be silently deduplicated.
• If scheduleContext.windowStart and startOffsetMinutes are present, the offset is the preferred portable schedule timing.
• durationMinutes describes how long the target should remain scheduled.
• startTime and endTime are useful display and fallback values, especially for apps that do not use a shared window model.
• If an importer sees conflicting offset and timestamp values, it should prefer the offset values when a valid schedule window exists.

Examples

Downloadable example files

These sample files can be used as fixtures when testing AstroPlan import support. They are real v1 payloads with schedule windows, target ordering, target notes, local timestamps, offsets, durations, and J2000 coordinate fields.

Extended framing schedule

The Heart and Soul example is an unmodified AstroGuide export using the registered captureStudioFraming extension. Its core coordinates preserve catalog-subject identity, while the extension carries the actual panel center, frame scale, position angle, filters, and equipment context.

The full extension definition and JSON Schema are maintained in the public AstroPlan repository.

Minimal target list

This is the smallest useful AstroPlan: a title, a creation time, and ordered targets with identifiers and coordinates.

{
  "version": 1,
  "title": "Galaxy Starter Plan",
  "author": "Example Planner",
  "created": "2026-07-28T18:30:00Z",
  "targets": [
    {
      "name": "Bode's Galaxy",
      "catalogId": "M81",
      "ra": "09h55m30s",
      "dec": "+69d03m54s",
      "rightAscensionHours": 9.925,
      "declinationDegrees": 69.065
    },
    {
      "name": "Cigar Galaxy",
      "catalogId": "M82",
      "rightAscensionHours": 9.9337,
      "declinationDegrees": 69.6797
    }
  ]
}

Scheduled observing plan

This example adds a time zone, night window, offsets, durations, and local timestamp strings. It can be imported as an ordered observing schedule.

{
  "version": 1,
  "title": "Cygnus Narrowband Night",
  "author": "AstroGuide",
  "created": "2026-07-28T18:30:00Z",
  "notes": "A portable observing schedule for a summer emission-region session.",
  "scheduleContext": {
    "timeZone": "America/New_York",
    "windowStart": "2026-07-29T01:00:00Z",
    "windowEnd": "2026-07-29T08:30:00Z"
  },
  "targets": [
    {
      "name": "North America Nebula",
      "catalogId": "NGC7000",
      "ra": "20h58m48s",
      "dec": "+44d19m00s",
      "rightAscensionHours": 20.98,
      "declinationDegrees": 44.3167,
      "startOffsetMinutes": 0,
      "durationMinutes": 120,
      "startTime": "2026-07-28T21:00:00-04:00",
      "endTime": "2026-07-28T23:00:00-04:00",
      "timeZone": "America/New_York",
      "notes": "Begin while the subject is climbing."
    },
    {
      "name": "Crescent Nebula",
      "catalogId": "NGC6888",
      "rightAscensionHours": 20.201,
      "declinationDegrees": 38.354,
      "startOffsetMinutes": 130,
      "durationMinutes": 90
    }
  ]
}

Interop guidance

Compatibility rules for app developers

• Writers should include version: 1.
• Readers should reject unsupported major versions only when they cannot safely continue.
• Readers should ignore unknown top-level and target-level fields.
• Writers experimenting with app-specific fields should use a namespaced key.
• Importers should resolve targets by catalog ID first, then exact name, then coordinates.
• Importers should clearly surface unresolved targets instead of silently dropping them.

The unknown-field rule is important. It allows future framing, mosaic, filter, exposure, and equipment metadata to appear in real files before every app supports every feature.

{
  "version": 1,
  "title": "Future Compatible Plan",
  "created": "2026-07-28T18:30:00Z",
  "futurePlannerField": "Readers should ignore this.",
  "targets": [
    {
      "name": "IC 1396",
      "catalogId": "IC 1396",
      "rightAscensionHours": 21.648333,
      "declinationDegrees": 57.488889,
      "vendor.example.framing": {
        "centerRightAscensionHours": 21.64,
        "centerDeclinationDegrees": 57.45,
        "rotationDegrees": 12.5
      }
    }
  ]
}