(Proposed ADIF 3.1.5 Resources, updated 2024/10/29)

Resources for Version 3.1.5 of the Amateur Data Interchange Format (ADIF) Specification

Introduction
ADX Schemas
1. Checks not Required
2. Limitations
ADIF Implementation Notes
Data Files Exported from ADIF Specification Tables
Test QSO Files based on ADIF Specification Tables
External Links

I. Introduction

This document gives details of resources that supplement the Amateur Data Interchange Format (ADIF) Specification version 3.1.5.

The resources are version-specific.

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 is specific to ADX 3.1.5 and disallows deprecated features.
Expected use is when exporting ADIF as ADX 3.1.5
adx315generic.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 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:

-1

10.37

.333

0008.50

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	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>

<value>

…

</header>

<value>

…

</record>

…

</dataTypes>

<value>

…

</header>

<value>

…

</record>

…

</enumeration>

…

<value>

…

</header>

<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" ?>

<value>Enumeration Name</value>

<value>Abbreviation</value>

<value>Meaning</value>

<value>Import-only</value>

<value>Comments</value>

</header>

<value name="Meaning">grayline</value>

</record>

<value name="Meaning">other</value>

</record>

<value name="Meaning">short path</value>

</record>

</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.

Resources for Version 3.1.5 of the Amateur Data Interchange Format (ADIF) Specification

Table of Contents

I. Introduction

II. ADX Schemas

II.A. Checks not Required

II.B. Limitations

III. Implementation Notes

III.A. Number Data Type

III.B. ADI Data Length Specifier

III.C. Minimum Fields

IV. Data Files Exported from ADIF Specification Tables

IV.A. Archive Structure

IV.B. Data File Contents

IV.B.1. Special Columns

IV.B.2. Enumerations Data File Contents

IV.B.3. Fields Data File Contents

IV.B.4. Extensible Markup Language Data File Contents

IV.B.5. Tab-separated Values Data File Contents

IV.B.6. Comma-separated Values Data File Contents

IV.B.7. Excel™ and Calc Data File Contents

IV.C. Notes for Developers

IV.C.1. Choosing a File

IV.C.2. Forwards Compatibility

IV.D. Application for Generating Export Files

V. Test QSO Files based on ADIF Specification Tables

V.A. Archive Structure

V.B. Test File Contents

V.C. Limitations

V.D. Application for Generating Test QSO Files

VI. External Links