Open Astrology Chart Format
An open, human-readable interchange format for astrological charts.
Open Astrology Chart Format is a portable, human-readable file format for a single astrological chart — a moment in spacetime, suitable for sharing between any astrology software. The format uses TOML, so a person can open, read, and hand-edit a chart file in any text editor.
A chart is one astronomically significant instant at one place on Earth: a birth, a transit, an event, an election. It is not a horoscope, a reading, or a wheel — those are interpretations or renderings of a chart.
Reference Implementation: github.com/ninthhousestudios/charts_dart
Spec Identity
Every conformant file begins with:
spec = "open-astrology-chart"
spec_version = 1File extension: .toml · Encoding: UTF-8 · Status: Draft
The Natural Key
A chart is defined by three values:
(jd, lat, lon)jd— Julian Day in Universal Time. The canonical, unambiguous instant.lat— Geographic latitude in decimal degrees.lon— Geographic longitude in decimal degrees.
Everything else — name, gender, place name, tags, notes — is metadata that describes whose moment it is. Metadata never participates in the natural key.
Design Principles
Julian Day is canonical. Civil calendar time and timezones are historically unstable, politically mutable, and ambiguous. The instant is stored as a single Julian Day number — unambiguous and tool-independent. Civil date/time is advisory, a convenience for humans, never the source of truth.
The natural key identifies the moment, not the person. Two charts may share a natural key while differing in metadata. Consumers must tolerate collisions rather than treating them as errors.
Human-readable, human-authorable. TOML means a person can open, read, and hand-edit a chart. A human authoring a chart knows the civil birth time, not the Julian Day — the format supports this without making jd non-canonical.
The file is the source of truth. Any database, index, or vector representation is a derived, rebuildable artifact. Sharing a chart means sharing its .toml file.
Field Reference
Moment
| Key | Type | Req | Meaning |
|---|---|---|---|
jd | float | yes | Julian Day in Universal Time. The canonical instant. |
Location
| Key | Type | Req | Meaning |
|---|---|---|---|
lat | float | yes | Latitude in decimal degrees. Positive = north. |
lon | float | yes | Longitude in decimal degrees. Positive = east. |
alt | float | no | Altitude in metres above sea level. |
placename | string | no | Free-text place label. |
country | string | no | Country name. |
Civil Time (Advisory)
A derived rendering of jd for human eyes. Advisory only — on any disagreement, jd wins.
| Key | Type | Req | Meaning |
|---|---|---|---|
date | string | no | Local civil date, YYYY-MM-DD. |
time | string | no | Local civil time, HH:MM:SS (24-hour). |
utc_offset | float | no | Base offset from UTC in hours, east-positive. |
dst_offset | float | no | Additional daylight-saving offset in hours. |
timezone | string | no | Named time zone label. |
Metadata
| Key | Type | Req | Meaning |
|---|---|---|---|
name | string | no | Subject or event name. |
gender | string | no | Gender of the subject. |
rodden | string | no | Rodden rating of data reliability. |
tags | array | no | Freeform user labels. |
notes | string | no | Free-text notes. |
Authoring
A human creating a chart by hand knows the civil birth time, not the Julian Day. The format supports this: write a file with only [civil] and [location], omitting [moment].jd. On first read, a conformant tool derives jd from the civil time and offset, then rewrites the file with [moment].jd populated. After that, jd is authoritative.
Examples
Minimal
spec = "open-astrology-chart"
spec_version = 1
[moment]
jd = 2447679.3388888887
[location]
lat = 40.045833
lon = -86.023611Full
spec = "open-astrology-chart"
spec_version = 1
name = "Jane Doe"
gender = "female"
rodden = "AA"
tags = ["celebrity", "vedic", "rectification"]
notes = """
Birth time from official records.
Rectified against two life events.
"""
[moment]
jd = 2447679.3388888887
[location]
lat = 40.045833
lon = -86.023611
alt = 235.0
placename = "Noblesville, IN"
country = "USA"
[civil]
date = "1989-12-14"
time = "20:08:00"
utc_offset = -5.0
dst_offset = 0.0
timezone = "EST"Human-Authored
A file a person can type by hand; a tool fills in [moment].jd on first read.
spec = "open-astrology-chart"
spec_version = 1
name = "Jane Doe"
[location]
lat = 40.045833
lon = -86.023611
placename = "Noblesville, IN"
country = "USA"
[civil]
date = "1989-12-14"
time = "20:08:00"
utc_offset = -5.0Conformance
A reader is conformant if it verifies the spec marker and rejects unknown spec_version; treats [moment].jd as canonical when present; derives jd from [civil] when jd is absent; and tolerates natural-key collisions and unknown keys without failing.
A writer is conformant if it emits the spec marker and spec_version; emits [moment].jd at full precision; omits absent optional fields; and produces stable, round-trippable output.
Round-trip fidelity: write → read → write must produce a byte-identical file. jd, lat, lon, and alt must preserve their full stored precision. Field ordering must be stable. Absent optional fields must not be emitted.