iof-xml-3
v0.1.0
Published
Type-safe parser, writer and XSD validator for IOF XML 3.0 (International Orienteering Federation Data Standard) files.
Maintainers
Readme
iof-xml-3
Type-safe parser, writer and validator for IOF XML 3.0, the IOF Data Standard used to exchange orienteering entries, start lists, results, courses and more.
- TypeScript types generated directly from the official
IOF.xsd(every message, type and enumeration, with the schema's documentation as TSDoc). - Parses all ten message types:
CompetitorList,OrganisationList,EventList,ClassList,EntryList,CourseData,StartList,ResultList,ServiceRequestList,ControlCardList. - Writes typed objects back to schema-ordered XML.
- Full XSD validation (libxml2 compiled to WebAssembly, so there is nothing native to build).
- Encoder and decoder for the compact binary
Routeformat. - ESM and CommonJS, Node 18 or later.
npm install iof-xml-3Reading
import { readFileSync } from 'node:fs';
import { parseResultList, personResults, fullName, formatDuration } from 'iof-xml-3';
const list = parseResultList(readFileSync('results.xml')); // string or bytes
console.log(list.Event.Name);
for (const { class: cls, result } of personResults(list)) {
const race = result.Result[0];
console.log(cls.Class.Name, fullName(result.Person.Name), race?.Status, race?.Time && formatDuration(race.Time));
}Use parseIofXml when the message type is not known in advance; it returns a discriminated union:
import { parseIofXml } from 'iof-xml-3';
const doc = parseIofXml(xml);
if (doc.root === 'StartList') {
doc.data.ClassStart; // typed as ClassStart[]
}How the XML maps to TypeScript:
| XML | TypeScript |
|---|---|
| attributes and child elements | properties with the same name as in the schema |
| repeating elements | always an array, empty when absent |
| optional single elements/attributes | optional properties |
| xsd:integer, xsd:double, xsd:decimal, xsd:boolean | number / boolean |
| xsd:date, xsd:dateTime, xsd:time | ISO 8601 string (offsets are preserved, nothing is converted) |
| elements with text and attributes (Id, Contact, Score, ...) | { value, ...attributes } |
| enumerations | string-literal unions plus a runtime array, e.g. ResultStatus and ResultStatusValues |
| Extensions | the raw parsed object (attributes prefixed with @_, text as #text) |
Times in results (Time, TimeBehind, split times) are seconds, as in the specification.
Schema defaults (for example ResultList@status="Complete") are not injected; they are documented as @default in the types.
Required elements and attributes are enforced while parsing and failures throw IofParseError with the path of the
offending node. Unknown elements are ignored unless you pass { strict: true }. Byte input is decoded using its BOM or
XML declaration, so ISO-8859-1 files from older software work. Prefixed IOF namespaces are supported.
Validating
import { validateIofXml, parseIofXmlAndValidate, IofValidationError } from 'iof-xml-3';
const { valid, errors } = await validateIofXml(xml); // errors: { message, line? }[]
try {
const doc = await parseIofXmlAndValidate(xml); // validates first, then parses
} catch (err) {
if (err instanceof IofValidationError) console.error(err.issues);
}Validation uses the official IOF.xsd embedded in the package. For very large files raise maxMemoryPages.
Writing
import { stringifyIofXml, stringifyIofXmlAndValidate } from 'iof-xml-3';
const xml = stringifyIofXml({
root: 'ResultList',
data: {
creator: 'My software',
Event: { Name: 'Sprint Cup' },
ClassResult: [
{
Class: { Name: 'M21' },
PersonResult: [
{
Person: { Name: { Family: 'Doe', Given: 'Jane' } },
Result: [{ Time: 1234.5, Position: 1, Status: 'OK' }],
},
],
},
],
},
});iofVersion and the namespace are added for you, repeating elements may be omitted, and elements are written in schema
order. stringifyIofXmlAndValidate additionally checks the output against IOF.xsd. Pass the namespaces of a parsed
document back in to keep Extensions content from other namespaces well-formed.
Routes
import { decodeRoute, encodeRoute, routeLength } from 'iof-xml-3';
const waypoints = decodeRoute(result.Route!.value); // { type, time: Date, latitude, longitude, altitude? }[]
routeLength(waypoints); // metres
result.Route = { value: encodeRoute(waypoints) };Development
npm run generate # regenerate src/generated from schema/IOF.xsd
npm test # validates, parses and round-trips every official example
npm run buildThe schema and examples in schema/ and examples/ come from the
IOF datastandard-v3 repository
(commit 24eb108), and the Route codec is a port of its C# reference implementation.
The repository did not state a license in the pages I checked; confirm the terms for redistributing the schema before publishing.
