(Proposed ADIF 3.1.5 Resources, updated 2024/10/29, annotated with changes from the previous release:
green
for additions, and
red
for deletions)
Resources for Version 3.1.5 3.1.4 of the Amateur Data Interchange Format (ADIF) Specification
Table of Contents
- Introduction
-
ADX Schemas
- Checks not Required
- Limitations
-
ADIF Implementation Notes
- Number Data Type
- ADI Data Length Specifier
- Minimum Fields
-
Data Files Exported from ADIF Specification Tables
- Archive Structure
-
Data File Contents
- Special Columns
- Enumerations Data File Contents
- Fields Data File Contents
- Extensible Markup Language Data File Contents
- Tab-separated Values Data File Contents
- Comma-separated Values Data File Contents
- Excel™ and Calc Data File Contents
-
Notes for Developers
- Choosing a File
- Forwards Compatibility
-
Application for Generating Export Files
-
Test QSO Files based on ADIF Specification Tables
- Archive Structure
- Test File Contents
- Limitations
- Application for Generating Test QSO Files
- External Links
I. Introduction
II. ADX Schemas
ADIF 3.0.2 introduced ADX as an alternative file format for representing
ADIF employing XML syntax.
The ADX XML Schemas supplement this, describing
ADX using the XML Schema definition language 1.0
The ADX schemas can be used to determine whether ADX complies with the ADIF specification.
If used, they must be applied externally without being referenced in the <ADX> root element.
Most aspects of the ADIF specification are validated, subject to
some checks that cannot be performed due to being advisory only and others which
are not possible or impractical to check.
Two schemas are provided:
-
adx315.xsd adx314.xsd is specific to ADX 3.1.5 3.1.4 and disallows deprecated features.
Expected use is when exporting ADIF as ADX 3.1.5
-
adx315generic.xsd adx314generic.xsd is not version-specific and includes deprecated features.
It is provided for situations where the ADX version is not known in advance and could be ADX 3.1.5 3.1.4 or earlier.
Expected use is when importing ADIF as ADX.
II.A. Checks not Required
-
CONTEST_ID element contents are not validated against the "Contest ID" enumeration because the ADIF
field type is "String" (i.e. the enumeration is advisory).
-
CNTY and MY_CNTY element contents are not validated against the "Secondary Administrative Subdivision"
enumeration because the enumeration values are controlled by external organizations and so are
subject to change without notice.
-
SUBMODE element contents are not validated against the "Submode" enumeration because the ADIF
field type is "String" (i.e. the enumeration is advisory).
II.B. Limitations
-
MY_STATE and STATE element contents are not validated against the "Primary Administrative Subdivision"
enumeration due to the excessively long regular expression required.
-
User-defined field names (contents of the USERDEF element nested in the HEADER element) are not
validated against the pre-defined ADIF field names due to the excessively long regular expression
required.
-
USERDEF elements nested in the HEADER element can optionally have either a RANGE or ENUM attribute
but not both; this is not validated.
-
Values in FIELDNAME attributes belonging to USERDEF elements nested in a RECORD element are not
validated against the USERDEF elements in the HEADER element.
-
USERDEF elements nested in RECORD elements do not have their contents validated against the TYPE,
RANGE or ENUM (if any) attributes of the corresponding USERDEF element nested in the HEADER element.
- APP element contents are not validated against the TYPE attribute (if any) given.
- In a record or in the header, no field may appear in more than one Data Specifier; this is not validated.
III. Implementation Notes
III.A. Number Data Type
Numbers conforming to the ADIF Number data type are always decimal (base 10).
Negative numbers are preceded by a minus sign (-).
However, positive numbers are not preceded by a plus sign (+).
Leading and trailing zeros are optional.
A decimal point (.) is optional.
Using locale-sensitive library routines to read or write ADIF numbers can produce incorrect results.
For example, a locale may specify that the character representing a decimal point is a comma -
this is not acceptable in ADIF.
Examples of valid ADIF Numbers:
Examples of invalid ADIF Numbers:
| +10.37 | (plus sign not allowed) |
| 0008,50 | (decimal point must be a dot (.)) |
| 1,000,000 | ("thousands separator" not allowed) |
| 10.100.500 | (only one decimal point allowed) |
| 0x3c | (only decimal numbers allowed) |
In some Number Data Type fields, although an integer value is typically used,
the ADIF specification does not restrict the value to integers.
Examples:
| <AGE:4>50.5 |
| <TX_PWR:3>7.5 |
Frequencies in fields are in Megahertz.
Kilohertz can be represented by digits to the right of a decimal point.
Examples:
| 14 | (14 MHz / 14000 kHz) |
| 10.1005 | (10.1005 MHz / 10100.5 kHz) |
| 0.472 | (0.472 MHz / 472 kHz) |
Similarly, power levels less than one Watt can be represented by digits to the right of a decimal point.
Examples:
| 100 | (100 Watts / 100000 milliwatts) |
| 7.5 | (7.5 Watts / 7500 milliwatts) |
| 0.25 | (0.25 Watts / 250 milliwatts) |
III.B. ADI Data Length Specifier
ADI data length specifiers are unsigned decimal (base 10) integers and may have values greater than, or equal to, zero.
Leading zeros are deprecated: they must not be created when exporting ADI,
but must be accepted when reading ADI because they were permitted in earlier versions of the ADIF specification.
Examples of valid data length specifiers:
| <COMMENT:0> |
| <NOTES:8>TEMP 24C |
Examples of data length specifiers valid only when importing:
| <COMMENT:000> |
| <NOTES:0008>TEMP 24C |
Examples of invalid data length specifiers:
| <NOTES:+8>TEMP 24C | (plus sign (+) not permitted) |
| <STX:3.0>001 | (specifier must be an integer) |
III.C. Minimum Fields
The ADIF specification does not specify what fields must be included in a record nor does a record necessarily have to represent a QSO.
The following is a guideline for a useful minimum set of fields to include in a record representing a QSO:
QSO_DATE, TIME_ON, CALL, BAND or FREQ, MODE
Importing applications such as
eQSL.cc,
LoTW
and
Club Log
typically impose additional requirements and
their documentation should be consulted for details.
The value in some fields is dependent on the value in another field, and in this case both fields should be included in a record.
For example, the interpretation of the STATE field value depends on the value in the DXCC field.
IV. Data Files Exported from ADIF Specification Tables
Machine-readable files containing data exported from the ADIF Specification’s tables are available
so that developers of ADIF-related software can use them to generate (for example) program data or SQL files.
The formats provided are:
- Extensible Markup Language (XML, file type .xml)
- Tab-separated values (TSV, file type .tsv)
- Comma-separated values (CSV, file type .csv)
- Microsoft™ Excel™ Workbook (file type .xlsx)
- Apache™ OpenOffice™ Calc (file type .ods)
A ZIP archive that includes the files is available from
https://adif.org.uk/version/resources
where
version is the ADIF version as a 3-digit number.
For example, for ADIF 3.1.5, the link is https://adif.org.uk/315/resources
IV.A. Archive Structure
The ZIP file contents include:
version
exports
csv
datatypes.csv
enumerations.csv
enumerations_name.csv
…
fields.csv
ods
datatypes.ods
enumerations. ods
enumerations_name.ods
…
fields.ods
tsv
datatypes.tsv
enumerations.tsv
enumerations_name.tsv
…
fields.tsv
xlsx
datatypes.xlsx
enumerations.xlsx
enumerations_name.xlsx
…
fields.xlsx
xml
adifexport.xsd
all.xml
datatypes.xml
enumerations.xml
enumerations_name.xml
…
fields.xml
where:
- version is the ADIF Specification version number as 3 digits, e.g. 315
- enumerations_name represents a set of files, with one for each Enumeration named name.
- datatypes.file-type files contain all Data Types.
-
enumerations.file-type files contain all Enumerations in file-type format (e.g. .xml).
Note that each enumeration has its own header row in the file.
- fields.file-type files contain all Fields.
- all.xml file contains all Data Types, Enumerations, and Fields.
The file names for individual enumerations are lowercase and have spaces replaced by underscores.
For example, the ARRL Sections table is exported as the file enumerations_arrl_sections.csv
IV.B. Data File Contents
The CSV, TSV, and XML files are UTF-8 encoded and start with the 3-byte BOM (0xEF, 0xBB, 0xBF).
(While ADIF ADI file contents are restricted to printable ASCII, carriage return, and line feed characters,
some ADIF Specification tables contain columns with printable non-ASCII characters such as accented letters in place names,
hence the use of UTF-8.)
Each whitespace character or sequence in cell values in the ADIF Specification is replaced with a single space character.
Formatting in the ADIF Specification is ignored.
Enumeration names have spaces replaced by underscores but the original case of the names is preserved,
e.g.
ARRL Section becomes
ARRL_Section.
The CSV, TSV, Excel™ and Calc files have the same row and column structure.
For example, the Ant_Path Enumeration at version 3.1.5 is exported as files with the name enumerations_ant_path.
file-type
and content along the following lines (note that the only newlines in the files are end-of-records in the CSV and TSV file types):
| Enumeration Name | Abbreviation | Meaning | Import-only | Comments | ADIF Version | ADIF Status |
|---|
| Ant_Path | G | grayline | | | 3.1.5 | Released |
| Ant_Path | O | other | | | 3.1.5 | Released |
| Ant_Path | S | short path | | | 3.1.5 | Released |
| Ant_Path | L | long path | | | 3.1.5 | Released |
The CSV, TSV, Excel™ and Calc enumerations.
file-type files contents are a concatenation of the
individual enumerations_
name.
file-type files.
A consequence is that there is one heading row per Enumeration rather than a single heading
row / record per file.
While the columns vary between the various Enumerations, the first column in the enumerations files is
always
Enumeration Name and that can be used to distinguish between the Enumerations.
IV.B.1. Special Columns
There are generated columns that do not exist in the ADIF Specification as such:
| Name | Description | Always Included |
|---|
| Import-only |
If the specification indicates somewhere within a table row that the item the row refers to is import-only (deprecated), the value will "true" in XML files and blank in other file types.
Otherwise, the value will not be included in XML files and be blank in other file types.
|
Yes |
| Comments | Sometimes the table cells with names in (e.g. data type names) contain additional information along the lines of "xxx (import-only; use yyy instead)". In these cases, the text within the parentheses is exported in the "Comments" column. | Yes |
| ADIF Version | All tables in all file types except for the XML files include this column, which contains the ADIF Specification version (e.g. 3.1.5). | Yes |
| ADIF Status | All tables in all file types except for the XML files include this column, which contains ADIF Specification status (Draft, Proposed, or Released). | Yes |
Minimum Value
Maximum Value |
The datatypes and fields files include these columns, which contain the minimum and maximum allowed numeric values for the data type or field or are blank.
Note that this does not include all numeric types and fields because ADIF does not specify the minimum or maximum allowed values for number types as imposed by data types within programming languages.
|
|
| Header Field | Values will be "true" in XML files or "Y" in other file types depending on whether field is a Header Field or a QSO field. | |
| DXCC Entity Code |
All the Primary Administrative Subdivision tables in the Specification are combined and this column is exported to differentiate between them.
Similarly, any Secondary Administrative Subdivision tables in the specification are combined and this column is exported to differentiate between them.
|
|
| Contained Within | Some of the Primary Administrative Subdivision tables include rows that span all columns in the table and contain the name/details of a locality that encloses the Primary Administrative Subdivisions defined within the following rows. These enclosing names/details are exported in this column. | |
| Deleted | Any entries within the Primary Administrative Subdivision tables that include the text "for contacts made before" will cause the Deleted column to contain "true" (XML files) or "Deleted" (other file types). | |
Only files that include an ADIF Status of "Released" should be used for production purposes; files with status "Draft" or "Proposed" are for testing / review purposes only.
IV.B.2. Enumerations Data File Contents
The Sponsored Award enumeration is not exported because its values are not defined within the ADIF Specification.
However, the table of sponsor names is exported with the name "Award_Sponsor".
In the Contest ID enumeration, Contest-ID values are always exported as uppercase, e.g. VIRGINIA QSO PARTY
In the Credit enumeration, the value "EWAS_ SATELLITE" is exported without the embedded space.
In the DXCC Entity Codes enumeration, the first column is exported with the title "Entity Code".
In the Modes enumeration, the Submodes column values are exported without the spaces after commas.
E.g. CHIP64,CHIP128
The Propagation enumeration is exported with the name "Propagation_Mode".
In line with this, the PROP_MODE field is exported with its Enumeration column set to "Propagation_Mode".
In the QSL_Upload_Status enumeration, the first column title "Via" is exported as the title "Status".
In the CREDIT_SUBMITTED and CREDIT_GRANTED fields, the data type is exported as "CreditList,AwardList", where the first data type in the list (CreditList) is current and the second item in the list (AwardList) is import-only (deprecated).
In the ADIF specification, different Primary Administrative Subdivision enumeration tables have different columns.
In the exported files, each enumeration has the full set of columns, even though some tables in the specification don’t include all of the columns. The columns concerned are: "Oblast #", "CQ Zone", and "ITU Zone".
IV.B.3. Fields Data File Contents
In the files containing fields, where a field's value is taken from one of a set of enumerations
depending on the value of a different field, the enumeration name will be suffixed by '[' followed by
the name of the other field followed by ']'.
For example, with the STATE field, the specific Primary Administrative Subdivision enumeration depends on
the value of the DXCC field, so the enumeration name will be included as:
Primary_Administrative_Subdivision[DXCC]
IV.B.4. Extensible Markup Language Data File Contents
This is an overview of the structure of the all.xml file:
<adif>
<dataTypes>
<header>
<value>
…
</header>
<record>
<value>
…
</record>
…
</dataTypes>
<enumeration>
<enumerations>
<header>
<value>
…
</header>
<record>
<value>
…
</record>
…
</enumeration>
…
<enumerations>
<fields>
<header>
<value>
…
</header>
<record>
<value>
…
</record>
…
</fields>
</adif>
All other XML files use the same structure except that they only have a <dataTypes> element, an <enumerations> element, or a <fields> element.
The <adif> document element includes version, status, and created attributes.
<value> elements within a <header> element contain the name of the header as the element contents.
<value> elements within a <record> element contain the name of the header as a name attribute and the value as the element contents.
Values are encoded in the same way as in the TSV files with the following exceptions:
-
Y (yes) values are encoded as the
XML Schema boolean datatype
value “true”.
-
Date values are encoded as the
XML Schema date datatype
UTC value.
For example, 2024-12-22Z
-
Where a value is blank (zero characters in length), the <value name=...> element will be omitted.
A schema file is supplied, named adifexport.xsd
Here is an example of enumerations_ant_path.xml
<?xml version="1.0" encoding="utf-8" ?>
<adif version="3.1.5" status="Released" created="2024-12-20T20:12:24Z">
<enumerations>
<enumeration name="Ant_Path">
<header>
<value>Enumeration Name</value>
<value>Abbreviation</value>
<value>Meaning</value>
<value>Import-only</value>
<value>Comments</value>
</header>
<record>
<value name="Enumeration Name">Ant_Path</value>
<value name="Abbreviation">G</value>
<value name="Meaning">grayline</value>
</record>
<record>
<value name="Enumeration Name">Ant_Path</value>
<value name="Abbreviation">O</value>
<value name="Meaning">other</value>
</record>
<record>
<value name="Enumeration Name">Ant_Path</value>
<value name="Abbreviation">S</value>
<value name="Meaning">short path</value>
</record>
<record>
<value name="Enumeration Name">Ant_Path</value>
<value name="Abbreviation">L</value>
<value name="Meaning">long path</value>
</record>
</enumeration>
</enumerations>
</adif>
IV.B.5. Tab-separated Values Data File Contents
Each record ends with a carriage return and line feed character pair.
Tab characters do not appear within cell values, so a row can be split based on tab characters without any issues with escaping.
IV.B.6. Comma-separated Values Data File Contents
Each record ends with a carriage return and line feed character pair.
Values are enclosed by double quotes (") and any double quotes embedded within a value are encoded
as a pair of double quotes.
For example, if a table cell in the ADIF Specification contains:
This value contains a double quotes " character
this will be the CSV value:
"This value contains a double quotes "" character"
CAUTION: do not open a CSV file in Excel™ or Calc without setting application options to ensure that
values are imported as text rather than numbers, dates, or times.
This is because the applications may change the cell contents, for example by removing leading zeros
from what they mistakenly perceive to be numbers.
Note that this issue does not apply to the Excel™ or Calc files because all cells are exported as text data types.
IV.B.7. Excel™ and Calc Data File Contents
These have a bold font in header rows.
Each workbook has one worksheet named as follows:
- "Data Types"
- "Enumerations"
- "name Enumeration" truncated to the Excel work sheet name limit of 31 characters.
- "Fields"
where
name is an enumeration name e.g. "ARRL_Section".
The files include some document and custom properties:
| Property | Value |
|---|
| Title |
"item exported from status ADIF Specification version"
where
- item is "Data Types", "Enumerations", "name Enumeration", or "Fields".
- version is the ADIF Specification version, e.g. "3.1.5"
- status is the ADIF Specification status of "Draft", "Proposed", or "Released".
E.g. "ARRL_Section Enumeration exported from Released ADIF Specification 3.1.5”
|
| Author | "ADIF Development Group" |
| ADIF Version | ADIF Specification version, e.g. "3.1.5".
This is a custom property. |
| ADIF Status | ADIF Specification status of "Draft", "Proposed", or "Released".
This is a custom property. |
IV.C. Notes for Developers
IV.C.1. Choosing a File
For copying and pasting table data, the Excel™ files are the best choice.
For accessing programmatically (for example to generate programming language source files,
SQL files, data files, or to update databases directly), the tab-separated values files are
simplest to deal with because the records can be split into values solely by specifying
a tab character to programming languages' "split" methods / functions.
The
Extensible Markup Language (XML)
files enable programming by using an object model along with
XML Path Language (XPATH)
expressions or by generating data declaratively using
XSL Transformations (XSLT).
IV.C.2. Forwards Compatibility
Future versions of the ADIF Specification may include changes in the structure of the tables such as:
- A change in a column's title.
- A change in the order of columns.
- Addition of columns.
- Removal of columns.
As far as possible, these types of changes will be avoided, but if they do occur, the files' contents will reflect them.
To cater for this, when accessing the files with software, it is recommended that the titles in the header records
are used to determine which column is which rather than relying on a column still being
the n
th column in future versions of ADIF.
Failing this, it is advisable that applications that assume the n
th column has a particular
data item in, check that the header record contains the expected title for that column.
IV.D. Application for Generating Export Files
For reference, the source code for the CreateADIFExportFiles application for Microsoft™ Windows™ used to create the export files is
available from GitHub.
The application will be updated for each new version of the ADIF Specification.
V. Test QSO Files based on ADIF Specification Tables
ADIF files containing test QSOs based on data exported from the ADIF Specification’s tables are available as:
- ADIF ADI (.adi)
- ADIF ADI (.adx)
A ZIP archive that includes the files is available from
https://adif.org.uk/version/resources
where
version is the ADIF version as a 3-digit number.
For example, for ADIF 3.1.5, the link is https://adif.org.uk/315/resources
V.A. Archive Structure
The ZIP file contents include:
version
tests
ADIF_version_test_QSOs_yyyy_mm_dd.adi
ADIF_version_test_QSOs_yyyy_mm_dd.adx
Entities_version_yyyy_mm_dd.xml
QSO_templates_version_yyyy_mm_dd.xslt
where:
- version is the ADIF Specification version number as 3 digits, e.g. 315
- yyyy is the year, mm is the month, and dd is the day.
- the Entities_... and QSO_templates... files are for diagnostic purposes only.
V.B. Test File Contents
The test QSO files include header fields, ADIF-defined QSO fields, application-defined QSO fields,
and user-defined QSO fields.
The aim is to incorporate all fields and values that are documented explicitly in the ADI Specification
and are not marked as import-only (deprecated) or deleted.
Where the ADIF Specification refers to values that are documented in external documents or on external websites
(for example enumeration values in the Secondary Administrative Subdivision table), at least one value will be included.
The ADI and ADX files have the same content except that the ADX file includes printable non-ASCII characters
in the field-name_INTL fields such as QTH_INTL.
Note: Care must be taken NOT to upload content from the test files to external services such as Club Log or LoTW!
V.C. Limitations
The QSOs are intended to be realistic but there are known limitations:
- BAND field values are selected pseudo-randomly, resulting in some improbable QSOs such as DX QSOs on microwaves.
- BAND, BAND_RX, FREQ, & FREQ_RX values are based on the ADIF Specification’s Band enumeration and may not be available in the contacted station’s country and / or the logging station’s country.
- Values in contacted station fields that have a relationship (such as DXCC, CONT, & CALL) may not always correspond to each other.
- Values in logging station fields that have a relationship (such as MY_DXCC, OPERATOR, OWNER_CALLSIGN, & STATION_CALLSIGN) may not always correspond to each other.
- QSOs containing a CONTEST_ID will frequently be on an inapplicable BAND, FREQ, BAND_RX, FREQ_RX, date, and time. The same applies to AWARD_SUBMITTED and AWARD_GRANTED.
V.D. Application for Generating Test QSO Files
For reference, the source code for the CreateADIFTestFiles application for Microsoft™ Windows™ used to create the test files is
available from GitHub.
The application will be updated for each new version of the ADIF Specification.
- Club Log APIs and Integration Notes
- eQSL ADIF Content Specifications
- GitHub
- GitHub CreateADIFExportFiles
- GitHub CreateADIFTestFiles
- LoTW Developer's Information (ARRL)
- XML Path Language (XPATH)
- XML Schema 1.0
- XML Schema Part 1: Structures Second Edition (W3C)
- XML Schema Part 2: Datatypes Second Edition: boolean (W3C)
- XML Schema Part 2: Datatypes Second Edition: date (W3C)
- XSL Transformation (XSLT)