GinXML Format

Format Overview

The root element identifies the document as GinXML and carries the current format version.

Current Version

1.1

Root Element

<ginxml>

Record Types

batch or recipe

<?xml version="1.0" encoding="UTF-8"?>
<ginxml format="GinXML" version="1.1" record_type="batch">
  ...
</ginxml>

Root attribute record_type distinguishes a full batch export from a recipe template export. Whenever application features add, remove, rename, or change the meaning of GinXML tags or attributes, this page should be updated in the same change.

Top-Level Structure

Each top-level block maps to a major area of the stored record. Recipe files intentionally omit batch-only sections such as cuts, output bottling, learning, and review. Internal database IDs are never serialized into GinXML; imports always get fresh IDs when saved.

Element	Purpose
`metadata`	Export and source record information.
`recipe`	Recipe descriptors and notes. Batch files may also include batch identity, distillation date, distiller, and equipment.
`base_charge`	Charge volume, ABV, absolute alcohol, target ABV, and resting time.
`botanicals`	Botanical recipe entries.
`distillation_log`	Ordered run log entries.
`cuts`	Heads, hearts, tails, total yield, and cut notes.
`output_bottling`	Final volume, ABV, dilution, bottle details, and appearance.
`sensory`	Structured aroma, structure, and serve evaluation.
`learning`	Retrospective notes and next-batch hypothesis.
`review`	Reviewer and review date.

Document Example

Example of a valid batch GinXML document with representative values and units.

<?xml version="1.0" encoding="UTF-8"?>
<ginxml format="GinXML" version="1.1" record_type="batch">
  <metadata>
    <exported_at>2026-05-19T08:30:00.000Z</exported_at>
    <app_name>Gin Creation Tracking App</app_name>
    <record_id>batch-record-id</record_id>
    <user_id>user-id</user_id>
    <created_at>2026-05-01T10:00:00.000Z</created_at>
    <updated_at>2026-05-19T08:20:00.000Z</updated_at>
  </metadata>
  <recipe>
    <recipe_name>House London Dry</recipe_name>
    <recipe_family>London Dry</recipe_family>
    <version>1.0</version>
    <distillation_date>2026-05-19</distillation_date>
    <distiller>Example Distiller</distiller>
    <still_equipment>2L copper alembic</still_equipment>
    <base_spirit>Neutral grain spirit</base_spirit>
    <intended_serve_goal>Gin and tonic</intended_serve_goal>
    <notes>Bright citrus, classic juniper lead.</notes>
  </recipe>
  <base_charge>
    <charge_volume unit="L">1.5</charge_volume>
    <charge_abv_percent>40</charge_abv_percent>
    <absolute_alcohol unit="L AA">0.6</absolute_alcohol>
    <target_final_abv_percent>42</target_final_abv_percent>
    <resting_time_days>7</resting_time_days>
    <auto_scale_botanicals>true</auto_scale_botanicals>
  </base_charge>
  <botanicals>
    <botanical id="juniper">
      <name>Juniper</name>
      <weight unit="g">20</weight>
      <grams_per_litre_aa>33.33</grams_per_litre_aa>
      <scale_locked>true</scale_locked>
      <form>whole</form>
      <preparation>lightly crushed</preparation>
      <method>macerated</method>
      <timing_notes>Overnight</timing_notes>
    </botanical>
  </botanicals>
  <distillation_log>
    <entry>
      <time>10:30</time>
      <stage_action>Hearts collection started</stage_action>
      <temperature unit="C">78.4</temperature>
      <output_volume unit="ml">250</output_volume>
      <distillate_abv_percent>78</distillate_abv_percent>
      <notes>Clean and bright.</notes>
    </entry>
  </distillation_log>
  <cuts>
    <heads_cut unit="ml">30</heads_cut>
    <hearts_collected unit="ml">500</hearts_collected>
    <tails_start_percent>55</tails_start_percent>
    <total_yield unit="ml">620</total_yield>
    <notes>Conservative heads cut.</notes>
  </cuts>
  <output_bottling>
    <final_volume unit="L">0.7</final_volume>
    <final_abv_percent>42</final_abv_percent>
    <dilution_water unit="ml">120</dilution_water>
    <bottling_date>2026-05-26</bottling_date>
    <number_of_bottles>1</number_of_bottles>
    <bottle_size unit="ml">700</bottle_size>
    <appearance_clarity>clear</appearance_clarity>
    <bottling_notes>Rested before bottling.</bottling_notes>
  </output_bottling>
  <sensory>
    <aroma>
      <juniper>
        <score_1_to_10>8</score_1_to_10>
        <notes>Fresh pine and resin.</notes>
      </juniper>
      <notes>Clean aromatic profile.</notes>
    </aroma>
    <structure>
      <balance>
        <score_1_to_10>7</score_1_to_10>
        <notes>Juniper-forward but integrated.</notes>
      </balance>
      <notes>Good structure.</notes>
    </structure>
    <serve>
      <gin_and_tonic_performance>
        <score_1_to_10>8</score_1_to_10>
        <notes>Opens well with tonic.</notes>
      </gin_and_tonic_performance>
      <notes>Best in long serves.</notes>
    </serve>
  </sensory>
  <learning>
    <worked_well>Citrus lift.</worked_well>
    <change_next_time>Reduce coriander slightly.</change_next_time>
    <next_batch_hypothesis>More angelica may improve length.</next_batch_hypothesis>
    <key_learning>Resting improved integration.</key_learning>
  </learning>
  <review>
    <reviewed_by>Example Reviewer</reviewed_by>
    <review_date>2026-05-27</review_date>
  </review>
</ginxml>

Recipe exports use the same root element with record_type="recipe". They keep metadata, recipe, base_charge, botanicals, distillation_log, and sensory, while omitting batch-only sections. Recipe base charge blocks may include charge volume, charge ABV, target final ABV, resting time, and auto-scale state.

Tag Reference

Field-by-field reference for each block currently emitted by the GinXML exporter.

`metadata`

All fields are strings. Timestamps use ISO format when available.

Batch files may include the full set below. Recipe files typically include recipe_name, recipe_family, base_spirit, intended_serve_goal, and notes.

exported_at
app_name
record_id
user_id
created_at
updated_at

`recipe`

Human-readable recipe and batch descriptors. Internal app IDs are not part of the GinXML payload.

recipe_name
recipe_family
version
distillation_date
distiller
still_equipment
base_spirit
intended_serve_goal
notes

`base_charge`

charge_volume with unit="L"
charge_abv_percent
absolute_alcohol with unit="L AA"
target_final_abv_percent
resting_time_days
auto_scale_botanicals

`botanicals`

Each botanical is represented as <botanical id="...">. The id attribute is optional.

name
weight with unit="g"
grams_per_litre_aa
scale_locked as true, false, or empty
form
preparation
method
timing_notes

`distillation_log`

Each log row is represented as an entry.

time
stage_action
temperature with unit="C"
output_volume with a unit attribute, usually ml
distillate_abv_percent
notes

`cuts`

heads_cut with unit="ml"
hearts_collected with unit="ml"
tails_start_percent
total_yield with unit="ml"
notes

`output_bottling`

final_volume with unit="L"
final_abv_percent
dilution_water with unit="ml"
bottling_date
number_of_bottles
bottle_size with unit="ml"
appearance_clarity
bottling_notes

Sensory Structure

Sensory contains aroma, structure, and serve. Each metric contains score_1_to_10 and notes.

`aroma`

juniper
citrus
spice
herbal_green
floral
earthy_rooty
sweetness_roundness
alcohol_heat
notes

`structure`

balance
complexity
integration
mouthfeel
cleanliness
finish_length
finish_quality
overall_quality
notes

`serve`

neat_performance
gin_and_tonic_performance
martini_performance
citrus_garnish_compatibility
general_mixing_versatility
notes

Learning And Review

Post-run reflection fields used to capture iteration notes and sign-off.

`learning`

worked_well
change_next_time
next_batch_hypothesis
key_learning

`review`

reviewed_by
review_date

Compatibility: import supports both GinXML and legacy YAML GinML files. Export creates GinXML. Batch screens can import recipe GinXML files as editable batch drafts, and recipe screens can import batch GinXML files by mapping the shared template fields.

Create the best gin ever, with GinXML

Format Overview

Top-Level Structure

Document Example

Tag Reference

metadata

recipe

base_charge

botanicals

distillation_log

cuts

output_bottling

Sensory Structure

aroma

structure

serve

Learning And Review

learning

review

`metadata`

`recipe`

`base_charge`

`botanicals`

`distillation_log`

`cuts`

`output_bottling`

`aroma`

`structure`

`serve`

`learning`

`review`