Open Archery Data Format

Version 1

OADF is a file package for archery training data: clubs, people, programmes, sessions, scores, equipment, sensor series, and photos.

It is designed so the same package can be:

  • read by an LLM (plain YAML and CSV, explicit fields, stable ids),
  • validated and pretty-printed by a formatter,
  • loaded into statistics tools (tables, joins on ids and timestamps).

Design goals

GoalHow
ExtensibleUnknown keys and unknown type / device ids are kept. New series devices need no schema bump.
LLM-friendlyOne fact, one place. Descriptive field names. Short documents. Units next to values.
Formatter-friendlyStrict YAML documents with a required oadf + type. Deterministic key order is recommended, not required.
Stats-friendlyScores are structured rows. Dense samples are CSV with a header. Times are UTC ISO-8601. Paths are relative to the package root.

Package

An OADF package is a directory (or a zip of that directory). The root contains oadf.yaml. All paths in documents are relative to that root, using / separators.

oadf.yaml
Athens Archery.club.yaml
people/maria.person.yaml
programmes/form-block.programme.yaml
archers/maria/2026-10-20.session.yaml
archers/maria/scorecards/2026-10-20-1820.scorecard.yaml
archers/maria/bulk/2026-10-20-1802.bulk.yaml
archers/maria/series/heart-2026-10-20.csv
archers/maria/media/end-1-1.jpg
archers/maria/equipment/indoor-recurve.equipment.yaml

A zip is only transport. Unpacking restores the same tree. The archive is not a document type.

Solo use is a package with one person and no club file. Club and coaching are optional.

Documents

TypeFile name patternRole
manifestoadf.yamlPackage version and optional index
club*.club.yamlMembers and coach→archer links
person*.person.yamlOne archer and/or coach
programme*.programme.yamlMulti-session plan, no scores
session_template*.session-template.yamlOne practice plan, no date
session*.session.yamlOne dated practice
scorecard*.scorecard.yamlScored arrows
bulk*.bulk.yamlArrow counts without per-arrow scores
equipment*.equipment.yamlOne gear item and its revisions
series*.csvDense samples (sidecar)
media*.jpg / *.png / *.webp / *.heicPhotos (sidecar)

YAML documents are UTF-8. Writers use \n. Readers accept \r\n. JSON with the same object shape is an allowed alternate encoding for any YAML document kind; the file then ends in .json instead of .yaml (for example *.session.json).

Every YAML document starts with:

oadf: 1
type: scorecard
KeyRequiredMeaning
oadfyesSchema major version. This document is 1
typeyesDocument kind from the table above (manifest uses type: manifest)

Unknown top-level keys are ignored by readers that do not understand them and must be written back unchanged when a tool rewrites the file. The same rule applies inside objects.

Manifest

oadf: 1
type: manifest
title: Athens Archery — Maria package
club: Athens Archery.club.yaml
people:
  - people/maria.person.yaml
  - people/elena.person.yaml
  - people/nikos.person.yaml
extensions: {}
KeyRequiredMeaning
titlenoPackage label
clubnoPath to the club document
peoplenoPaths to person documents
extensionsnoMap for tool-specific package metadata

The manifest does not list every session. Tools discover files by extension and type.

Shared types

Id. Lowercase letters, digits, and hyphens. Starts with a letter or digit. Length 1–64. Examples: maria, mantis, indoor-recurve.

Path. Relative to the package root. No leading /. No .. segments that escape the package.

Calendar date. YYYY-MM-DD. Must be a real date.

UTC time. ISO-8601 with Z, optional fractional seconds. Example: 2026-10-20T13:46:12.340Z.

Face point. Origin at target centre. +x right, +y up. Face radius is 10 (outer edge of a full face). Writers emit at most one decimal place for scores plots; readers accept more.

Score. One of:

ValuePointsMeaning
"X"10Inner ten when the face has one
10 … 1that valueRing score (YAML integer)
"M" or 00Miss; the arrow was shot
null / omittednoneNot entered

X counts as a ten in totals. Whether a plotted 10 sits in an inner ten is an app face rule; the file stores what was entered.

Quantity. Object with value (number) and unit (string). Example: { value: 18, unit: m }.

Extension map. Any object under extensions is namespaced by tool id:

extensions:
  rcherry:
    liveCode: AB12
  other-app:
    note: kept even if unknown here

Club

oadf: 1
type: club
id: trilofos-archery
title: Athens Archery
description: Indoor hall club.
members:
  - { person: maria, roles: [archer] }
  - { person: elena, roles: [coach] }
  - { person: nikos, roles: [coach, archer] }
coaching:
  - { coach: elena, archers: [maria, nikos] }
  - { coach: nikos, archers: [maria] }
KeyRequiredMeaning
idyesStable club id
titleyesDisplay name
descriptionnoFree text
membersyesMembership list
members[].personyesPerson id
members[].rolesyesNon-empty. Known: archer, coach. Others kept
coachingnoCoach→archer assignments
coaching[].coachyesPerson id
coaching[].archersyesPerson ids (one coach, many archers)

An archer may appear under more than one coach. Roles on membership are not the same as coaching links.

Person

oadf: 1
type: person
id: maria
title: Maria P.
club: trilofos-archery
KeyRequiredMeaning
idyesStable person id
titleyesDisplay name
clubnoClub id
descriptionnoFree text

Programme

A programme is publishable and self-contained. It holds no scores and no file paths to recorded sessions.

oadf: 1
type: programme
id: form-block
title: Form block
description: Two practices. Volume, then a scored card.
units:
  - index: 1
    title: Volume
    blocks:
      - type: text
        body: Blank bale only. Stop at 120 arrows.
      - type: bulk
        label: Blank bale
        targetArrows: 120
  - index: 2
    title: Score
    blocks:
      - type: text
        body: One WA 18 card. Record the sight if it is connected.
      - type: scorecard
        label: WA 18
        devices: [mantis, heart-rate, wii-balance]
        config:
          endsPerCard: 2
          arrowsPerEnd: 3
          cards: 1
          round: WA 18 (40cm)
          distance: { value: 18, unit: m }
          face: { value: 40, unit: cm }
          indoor: true

units[].index is 1-based and unique. Block type values in version 1: text, scorecard, bulk. Unknown block types are kept.

Session template

Same block list as a programme unit, without a date and without recorded paths.

oadf: 1
type: session_template
title: WA 18
blocks:
  - type: text
    body: Twenty arrows on the blank bale, then one scored card.
  - type: bulk
    label: Blank bale
  - type: scorecard
    label: WA 18

Session

One practice on one calendar date. Recorded arrows live in linked scorecard and bulk files.

oadf: 1
type: session
date: 2026-10-20
archer: maria
programme: form-block
unit: 2
programmePath: programmes/form-block.programme.yaml
location: Club hall
indoor: true
equipment:
  - { id: indoor-recurve, type: bow, title: Indoor recurve, rev: 1, at: 2026-09-01T08:00:00Z }
blocks:
  - type: text
    body: Twenty arrows on the blank bale, then one scored WA 18 card.
  - type: bulk
    label: Blank bale
    path: archers/maria/bulk/2026-10-20-1802.bulk.yaml
  - type: scorecard
    label: WA 18
    path: archers/maria/scorecards/2026-10-20-1820.scorecard.yaml
series:
  - device: heart-rate
    attach: file
    path: archers/maria/series/heart-2026-10-20.csv
media:
  - kind: photo
    attach: file
    path: archers/maria/media/session-hall.jpg
KeyRequiredMeaning
dateyesCalendar date
archernoPerson id
programmenoProgramme id
unitno1-based unit index
programmePathnoPath to the programme file
locationnoFree text
indoornoBoolean
equipmentnoGear used that day (see Equipment references)
blocksyesOrdered steps
seriesnoSeries attachments for the whole practice
medianoMedia attachments for the whole practice

Empty path on a scorecard/bulk block means the step exists but has not been started.

Scorecard

oadf: 1
type: scorecard
archer: maria
session: archers/maria/2026-10-20.session.yaml
round: WA 18 (40cm)
distance: { value: 18, unit: m }
face: { value: 40, unit: cm }
indoor: true
location: Club hall
grid:
  endsPerCard: 2
  arrowsPerEnd: 3
  cards: 1
notes:
  training: Quiet hall, first scoring end.
  cards: [Watch the left hand.]
equipment:
  - { id: indoor-recurve, type: bow, title: Indoor recurve, rev: 1, at: 2026-09-01T08:00:00Z }
cards:
  - ends:
      - note: Held long on the second arrow.
        arrows:
          - { score: X, x: 0.1, y: 0.2, at: 2026-10-20T13:46:12.340Z }
          - { score: 9, x: 1.0, y: -0.5, at: 2026-10-20T13:46:18.100Z }
          - { score: 8, x: -0.4, y: 0.6, at: 2026-10-20T13:46:30.000Z }
      - note: Called the first arrow out.
        arrows:
          - { score: M, x: 8, y: 3, at: 2026-10-20T13:50:00.000Z }
          - { score: 10, at: 2026-10-20T13:50:12.000Z }
          - { at: 2026-10-20T13:50:20.000Z }
series:
  - device: mantis
    kind: aim
    attach: shot
    key: 1.1.1
    path: archers/maria/series/aim-1-1-1.csv
    hz: 400
    origin: release
    breakIndex: 1
    unit: deg
media:
  - kind: photo
    attach: end
    key: "1.1"
    path: archers/maria/media/end-1-1.jpg
  - kind: photo
    attach: shot
    key: "1.1.2"
    path: archers/maria/media/shot-1-1-2.jpg

Grid and cards

KeyRequiredMeaning
grid.endsPerCardyesPlanned rows per card (1–60)
grid.arrowsPerEndyesPlanned arrows per end (1–24)
grid.cardsyesPlanned card count (1–10)
cardsyesRecorded cards in order

Each card has ends (array). Each end has:

KeyRequiredMeaning
arrowsyesLength may be shorter than arrowsPerEnd; missing slots are not entered
notenoFree text for that end

Each arrow object:

KeyRequiredMeaning
scorenoScore value as above
x, ynoFace point
atnoUTC release / entry time

Empty arrow {} is allowed. A timed but unscored shot is { at: ... } only.

Card index, end index, and arrow index are 1-based when used as keys (1.1.2 = card 1, end 1, arrow 2).

Totals

Writers may omit cached totals. Readers and stats tools recompute:

  • points: X→10, M/0→0, integers as written,
  • only arrows with a score count,
  • blank / timed-only arrows do not count as misses.

Attachment keys

attachkey
shotcard.end.arrow (example 1.1.2)
endcard.end (example 1.1)
roundbulk round number as string or integer
fileomit key

Bulk

oadf: 1
type: bulk
archer: maria
location: Club hall
indoor: true
distance: { value: 5, unit: m }
rounds:
  - { arrows: 20, at: 2026-10-20T16:02:14.742Z }
  - { arrows: 10, at: 2026-10-20T16:03:25.589Z }
series:
  - device: wii-balance
    attach: round
    key: 1
    path: archers/maria/series/balance-round-1.csv
KeyRequiredMeaning
roundsyesIn commit order
rounds[].arrowsyesInteger ≥ 1
rounds[].atyesUTC time

Series (CSV sidecars)

Dense samples never live inside YAML. YAML holds a descriptor; CSV holds rows.

Descriptor fields (on session, scorecard, or bulk)

KeyRequiredMeaning
deviceyesDevice id (mantis, heart-rate, wii-balance, or any new id)
attachyesshot / end / round / file
keywhen not fileAttachment key
pathyesPackage path to the CSV
kindnoRegistered meaning. Version 1 registers aim
channelsnoColumn schema when not implied by kind
hznoSample rate when time is implicit
originnorelease or start
breakIndexnoSample index of release when origin: release
unitnoShared unit when all channels share one
timenoiso when the CSV first column is UTC time

Identity of a payload: device + attach + key (+ owning file). If duplicated, readers use the first and still preserve the rest on rewrite.

CSV rules

  • UTF-8, , separator, \n lines.
  • First row is a header.
  • Numbers are finite decimals. Empty cells are missing values.
  • Writers do not put comments in CSV.

Aim (kind: aim). Columns: yaw,pitch in degrees. +yaw right, +pitch up. Sample i is at (i - breakIndex) / hz seconds from release when origin: release. No time column.

yaw,pitch
0.012,-0.004
0,0
-0.020,0.008

Generic series. Either:

  1. time column (ISO UTC) plus one column per channel, or
  2. no time column, with hz + origin on the descriptor (row index → time).

Heart rate example descriptor: device: heart-rate, attach: file, time: iso. CSV:

time,bpm
2026-10-20T13:46:10.000Z,74
2026-10-20T13:46:12.340Z,78

Balance around release: channels tr,br,tl,bl in kg; hz + origin: release + breakIndex.

Channel names are unique within one CSV. Units belong on the descriptor (channels: [{ name: bpm, unit: bpm }]) so stats tools and LLMs do not guess.

Limits (version 1)

FieldRange
Scorecard cards1–10
Ends per card1–60
Arrows per end1–24
Bulk arrows in one roundinteger ≥ 1
Series sample rate1–4000 Hz
Aim window before/after release1–15 s when given
Aim samples in one trace2–13000

Media

Binary files only. YAML descriptors list them; bytes are never inlined.

media:
  - kind: photo
    attach: end
    key: "1.1"
    path: archers/maria/media/end-1-1.jpg
KeyRequiredMeaning
kindyesphoto in version 1; other kinds kept
attachyesSame as series
keywhen not fileSame as series
pathyesPath to the binary

Equipment

One physical item, one file, full revision history. props on each revision is the full state after the change, not a patch.

oadf: 1
type: equipment
id: indoor-recurve
equipmentType: bow
title: Indoor recurve
brand: hoyt
owner: maria
description: Hall bow.
revisions:
  - rev: 1
    at: 2026-09-01T08:00:00Z
    props:
      bowType: recurve
      size: { value: 68, unit: in }
      drawWeight: { value: 34, unit: lb }
      parts: [shibuya-ultima, longrod-30, string-8190]
  - rev: 2
    at: 2026-11-02T18:00:00Z
    props:
      bowType: recurve
      size: { value: 68, unit: in }
      drawWeight: { value: 34, unit: lb }
      limbs: Wiawis NS
      parts: [axcel-achieve, longrod-30, string-8190]
media:
  - kind: photo
    attach: file
    path: archers/maria/media/indoor-recurve.jpg
KeyRequiredMeaning
idyesStable id
equipmentTypeyesOpen token: bow, arrow, sight, stabilizer, weight, string, brand, …
titleyesDisplay name
brandnoBrand equipment id
ownernoPerson id
revisionsyesOrdered; rev ≥ 1 unique; at UTC

The state at time T is the revision with the greatest at ≤ T.

Field name is equipmentType so it does not clash with document type.

Reference from a session or scorecard

equipment:
  - id: indoor-recurve
    type: bow
    title: Indoor recurve
    rev: 1
    at: 2026-09-01T08:00:00Z

id is required. type, title, rev, and at snapshot the day so the practice still reads if the equipment file is missing.

Known property keys by equipmentType

equipmentTypeProperty keys
bowbowType, size, drawWeight, braceHeight, tiller, limbs, string, nockingPoint, parts
arrowspine, length, diameter, pointWeight, vanes, nock, count
stabilizerrole, length, weights
weightmass, mount
sightextension, magnification, marks
stringmountedOn, strands
brandnone required

Measured values use { value, unit }. marks is [{ distance, unit, mark }]. Unknown property keys are kept.

Extensibility

  1. New device. Add a series descriptor with a new device id, channels with units, and a CSV. No schema version bump.
  2. Registered kind. When several apps share meaning (as with aim), document a kind and its columns in a newer OADF major version. Until then, channels on the descriptor is enough.
  3. New session block. New blocks[].type string + fields. Older tools keep the object.
  4. New document kind. New type + file name pattern. Do not overload scorecard / bulk.
  5. New equipment type. New equipmentType token + property keys.
  6. New media kind. New media[].kind; keep attach / path.
  7. Tool private data. Use extensions.<toolId> maps. Foreign tools round-trip them.

Breaking changes bump oadf to a new major version. Additive open-token growth does not.

Conformance

A reader:

  • Requires oadf: 1 and type on YAML documents.
  • Resolves paths from the package root.
  • Recomputes score totals from arrows.
  • Leaves missing scores missing (does not invent misses).
  • Loads series only from CSV sidecars named by descriptors.
  • Keeps unknown keys, unknown block types, unknown devices, unknown equipment types.
  • Accepts JSON documents with the same shape.

A writer:

  • Emits UTC times as ISO-8601 Z.
  • Emits face coordinates with +y up, radius 10.
  • Emits series and photos as sidecars, never inlined bytes or sample matrices in YAML.
  • Uses 1-based card.end.arrow keys.
  • Round-trips unknown fields it does not own.
  • May omit club/person files in a solo package.

Worked package

See the example/ directory in this repository. Bluetooth radio layouts stay in bluetooth.md and feed aim CSV columns; they are not part of the YAML encoding.