Trusted GAbbI

(Global Amateur Interchange)

Format

May 20, 2002

Version 0.25

By Darryl Wagoner, WA1GON

wa1gon@arrl.net

and

Michael Keane, K1MK

k1mk@alum.mit.edu

© 2002 Trusted QSL and The American Radio Relay League

Discussion

A basic philosophy guiding data interchange is: “Be conservative in what you generate; be liberal in what you accept.” Following this precept, the affirmative obligation falls upon the sender to covert data, which may be stored in a local or proprietary format, into the specified  format for interchange prior to transmission to the recipient.

Thus, one will find in this document that the strictest  requirements for formatting and content are levied upon the GAbbI writer. A GAbbI reader on the other hand, is allowed to be more tolerant and less absolutist when applying these rules and deciding what constitutes valid data that it might  be willing to accept.

The  acceptance of non-compliant data is wholly at the discretion of the receiver. In addition  to  being liberal in what it accepts,  a GAbbI reader would be well advised to also keep in mind another principle when deciding how to dispose of malformed fields and records: “First, do no harm.”

1.   Physical Specifications

Files

·       A logical file shall be composed of a  header area and a data area..

·       The header area shall proceed the data area.

·       The header area shall consist of zero or more records and be terminated by an end of header tag.

·       The data area shall consist of zero or more records and be terminated by an end of file tag.

Records

·       Records shall be composed of zero or more fields.

·       Records shall be separated by record separator tags.

Character Set

·       The "character set" shall be ISO/IEC 10646-1:2000 UCS ("Unicode Version 3.0")

·       Default encoding of characters shall be UTF-8

·       Readers may support UTF-16 encoding [TBR]

o      A GAbbI file object that is encoded in UTF-16 shall begin with a two octet signature of #xFEFF (Zero Width No-Break Space; Byte Order Mark)

·       A compliant GAbbI reader shall check for the BOM signature. If the BOM signature is encountered indicating that the following file object is UTF-16 encoded and the reader cannot process UTF-16, the reader shall generate a fatal error

Fields

<Field_Name:Field_Length[:Field_Type]>Field_Value

E.g., <Call:4>K1MK

Field_Name — A sequence of one (1) to thirty-two (32) [TBR] characters from the set: [A-Za-z0-9/.?_+:=!@#$%^&*-] [TBR]. In determining equivalence and uniqueness Field_Names shall be treated as case insensitive,  i.e. CALL, call, Call  and CaLl are equivalent Field_Names.

Use of Field_Names beginning with the character sequences GABBI_ and SIGN_ shall be reserved for use in the specification. All other legal Field_Names may be used for local field definitions created by users.

Field_Length — Specification of the length of Field_Value in Unicode characters (not bytes or octets and not symbols or graphemes). The specification is a non-negative decimal integer with no leading zeros and shall be constructed from the characters [0-9].

Field_Type (Optional) A specification of the type of the field value. Treated as case insensitive.

Field_Value— A sequence of Field_Length characters that represents the value of the field.

Separator Tags

As with field names, separator tags shall be treated as case insensitive.

<eoh> — End of header area. <eoh> shall be present in every GAbbI file object. <eoh> signals the end of the header area and start of the data area.

<eor> — End of physical record.

<eof>— End of logical file. <eof> shall be present in every GAbbI file object. <eof> signals the end of the data area. Upon encountering <eof> a GAbbI reader shall reset its internal state; a new GAbbI header may follow immediately (or physical EOF may follow).

2. Field Type Definitions

Type

Designator

Description

Base64

6

Base 64 encoded number (binary string). Line length of base64 encoded objects shall be limited to 72 characters and lines shall be broken by use of end-of-line character(s). Legal characters that may appear in the value field are [A-Za-z0-9./=].

Binary

B

Fixed point (integer) number in base 210 (binary) representation. Written in big-endian order, starting with most significant bit. Legal characters that may appear in the value field are [0-1-].

Character

C

Character string. Valid characters that may appear in the value field are the set of displayable characters (printable characters plus <SP> and <HT>). [TBR]

Date

D

Date in ISO 8601 format. Extended format i.e., YYYY-MM-DD , is preferred but basic format, YYYYMMDD, is permissible but its use is deprecated. Valid characters that may appear in the value field are [0-9-][1] .

Enumeration

E

A character string from an enumerated list of character strings. The comparison of a Field_Value to an enumerated value is case insensitive. Valid characters that may appear in the value field are the set of displayable characters (printable characters plus <SP> and <HT>). [TBR]

Floating Point

F

Floating-point number in base 1010 (decimal) representation. Legal characters that may appear in the value field are [0-9.-].

Hexadecimal

H

Fixed point (integer) number in base 1610 (hexadecimal) representation. Legal characters that may appear in the value field are [0-9A-F-].

Integer

I

Fixed point (integer) number in base 1010 (decimal) representation. Legal characters that may appear in the value field are [0-9-].

Multi-Line

M

Character string. Legal characters that may appear in the value field are displayable characters. An implementation independent end-of-line delimiter (the two character sequence <CR><NL>) shall be transmitted to signal logical line breaks. [TBR]

Numeric

N

A general format number. Use of N is deprecated; field types IBOH or F are the preferred alternatives.

Octal

O

Fixed-point (integer) number in base 810 (octal) representation. Legal characters that may appear in the value field are [0-7-].

Time

T

Time in ISO 8601 format. Extended format i.e., hh:mm:ssZ is preferred, but basic format, hhmmssZ, and basic format with reduced precision, hhmmZ, are also permissible. Should the time zone designator ‘Z’ be omitted, UTC shall be assumed. Legal characters that may appear in the value field are [0-9A-Z:].

3. Field Definitions

tCERT (Identity certificate) Record

Each GAbbI file shall contain at least one tCERT record. 

Name

Type

Required

Max Size (chars)

Description

CERTIFICATE

6

Y

2048

X.509 v3 identity certificate. Base64 encoded distinguished encoding representation (DER) of the certificate. 

CERT_UID

I

Y

1

A one digit locally unique identifier (UID) for this tCERT record. Unique within a GAbbI logical file.

REC_TYPE

E

Y

10

Always "tCERT". This declares the record to be an identity certificate record.

tCONTACT (Trusted Contact) Record

The tCONTACT record contains information that is unique to a specific contact. Note that most of the fields are required. This is because these fields can be expected to differ for each contact. For the sake of transmission and reception efficiency, the information that is shared in common by several contacts is grouped together and placed into a tSTATION record. The information contained in the tSTATION record is included in the virtual QSL record by means of the STATION_GUID field. Each GAbbI file shall contain at least one tCONTACT record. 

Name

Type

Required

Category

Max Size (chars)

Description

BAND

E

Y

 

6

The band on which contact took place. Describes a two-way (non-crossband) contact[2]. Format for interchange is the band designation in upper case See Table 1 for a list of the legal values for the enumeration.

CALL

C

Y

 

15

The call sign of station contacted. Call sign is insensitive to case. Legal values for characters that may appear in a call sign are [A-Z0-9/].

CERT_UID

I

Y

 

1

This is a one digit locally unique identifier (UID) of  the tCERT record containing a copy of  the certificate used to sign the logical record. Unique within a GAbbI logical file.

FREQ

F

N

 

8

Frequency. Describes a two-way (non-crossband) contact[3] . Format for interchange shall be frequency in MHz with no greater than 100 mHz precision. A decimal point shall be included. There shall be no leading zeros; there shall be no trailing zeroes after the last significant digit. 

If the precise frequency is unknown use the Frequency listed in Table 1 for the band may be used.

MODE

E

Y

 

6

Mode. Describes a two-way (non-crossmode) contact. Format for interchange is the mode identifier in upper case. See Table 2 for a list of the legal values for the enumeration.

QSL

E

N

 

3

A value of “PSE” shall indicate that a confirmation is requested in reply; a value of “TNX” shall indicate that a response is not necessary

QSO_DATE

D

Y

 

8

Date in ISO 8601 format. Extended format i.e., YYYY-MM-DD, is the preferred format. Basic format, YYYYMMDD, is permissible but its use is deprecated

QSO_TIME

T

Y

 

9

UTC Time in ISO 8601 format. Extended format, hh:mm:ssZ, is the preferred format. Both basic format, hhmmssZ, and basic format with reduced precision, hhmmZ, are permissible but their use is deprecated. In the event that the time zone designator ‘Z’ is omitted, UTC shall be assumed

REC_TYPE

E

Y

 

10

Always "tCONTACT". This declares the record to be a Trusted Contact record.

REMARKS

M

N

 

256

Operator remarks regarding this contact.

RST_SENT

C

N

 

8

Signal Report Sent. Comparison of values of RST_SENT is insensitive to case. 

SIGN_LOTW_V1.0

6

Y

Signature

172

This is the ARRL LOTW v1.0 digital signature of this record. See Appendix A for the specific of this signing rule. Maximum field size based on 1024-bit key and base64 encoding

STATION_UID

I

Y

 

2

This is a two digit (locally) Unique Identifier (UID) of the tSTATION record associated with this tCONTACT record. Unique within a GAbbI logical file.

tHEADER (GAbbI Header) Record

The tHEADER record is optional but one GAbbI header record should be present in each GAbbI file.

Name

Type

Required

Max Size (chars)

Description

CATEGORY

E

Y

4

Declares category of data in this file. To indicate trusted (digitally signed) QSL data the value of CATEGORY shall be "tQSL"

GAbbI_#_CONTACT_RECS

I

N

4

Number of tCONTACT records that can be expected to follow in this logical file. Use is optional, but if present, the value shall be correct. Reader may issue an error message if the number of valid tCONTACT records received is different from the value declared in the header 

GAbbI_#_STATION_RECS

I

N

2

Number of tSTATION records that can be expected to follow in this logical file. Use is optional, but if present, the value shall be correct. Reader may issue an error message if the number of valid tSTATION records received is different from the value declared in the header 

GAbbI_CREATED_BY

C

N

64

Name and version of program creating this file.

GAbbI_CREATED_ON

C

N

20

ISO 8601 Date & Time that file was created.

GAbbI_MESSAGE_DIGEST

E

N

5

Message digest algorithm: SHA-1 (default) or MD5[5].

GAbbI_SENDER

C

N

15

The call sign of station creating the file. SENDER may differ from the value of the CALL field in tSTATION records in certain cases, such as a QSL Manager

GAbbI_SIGN_ALOGORITHM

E

N

5

Digital signature key type algorithm: RSA (default), DSA or ECDSA[5]

GAbbI_VERSION

C

Y

4

GAbbI version

REC_TYPE

E

Y

10

Always "tHEADER". This declares the record to be a GAbbI header record.

tSTATION (Trusted Station) Record

The tSTATION record contains information that is common to a set of logical QSL records; each logical QSL record provides the trusted (signed) set of information needed to confirm a QSO. Each GAbbI file shall contain at least one tSTATION record

When a field appears in a tSTATION record, it specifies the default value for the field in each logical record, which references a tSTATION record via the STATION_GUID field.  In constructing the logical QSL record from the tSTATION and tCONTACT records, the order of precedence shall be: appearance of a field in the tCONTACT record will supersede any default value for that field that may have been established by the appearance of the same field in the linked tSTATION record. 

Name

Type

Required

Category

Max Size (chars)

Description

CALL

C

Y

 

15

Call sign used by the station reporting this contact. Call sign is insensitive to case. Legal value for call sign characters are [A-Z0-9/].

CL_CITY

E

N

Sub_Gov3

6

Chilean Municipality (“Comuna”). Format for interchange shall be the 5 or 6  digit code for the municipality. Consult list. from Federachi for the legal values of the enumeration.

CONT

E

N

 

2

Continent. Format for interchange shall be the two-letter abbreviation in upper case. See Table 5 for legal values of the enumeration.

CQZ

E

N

 

2

CQ Zone. Format for interchange shall be two numeric characters and must include any leading zero. (01  £ CQZ £  40)

CZ_DISTRICT

E

N

 

3

Czech district (“okres”). Interchange format is a three letter abbreviation; consult list from CRC for the legal values of the enumeration.

DIG

I

N

 

5

Diplom Interessen Gruppe (DIG) member number.

DOK

E

N

 

3

DARC District Location Code (DOK). DOK is a three (3) character string consisting of one (1) alpha character [A-IK-Z] and two (2) digits (see DARC list).

DXCC

E

Y

 

3

ARRL DX Century Club. Numeric identifiers from the ARRL. Format for interchange shall be three digits and must include any leading zeroes. See Table 6 for legal values.

EMAIL_ADDRESS

C

N

 

64

Electronic mail address to use for contacting this station or operator

GRIDSQUARE

C

N

 

6

Either the 4 character or the 6 character Maidenhead grid square designator is acceptable. Format for interchanges shall be AANN and AANNaa. Comparison of values of GRIDSQUARE is insensitive to case. For stations located on grid intersections, multiple instances of the  GRIDSQUARE field may appear in a single  tSTATION record, up to a maximum of four.

IOTA

E

N

 

6

RSGB Islands on the Air (IOTA) Program reference number. Format for interchange shall be six characters consisting of a two-letter continental abbreviation in upper case immediately followed by a hyphen immediately followed by three numeric characters that must include any leading zeroes. Comparison of IOTA designators shall be case insensitive. Consult the RSGB IOTA Program reference numbers list for legal values of the enumeration.

ITUZ

E

N

 

2

ITU Zone. Format for interchange shall be two numeric characters and must include any leading zero. (01  £ITUZ£ 75)

JAG

I

N

 

5

Japan Award Hunters Group member number

JP_CITY

E

N

Sub_Gov2

4

Japanese city ("shi"). Format for interchange is the JCC reference number for the city from JARL list: four numeric digits including any leading zeros. N.B.: JARL’s internal numbering scheme for prefectures differs from ISO 3166-2.

JP_GUN

E

N

Sub_Gov2

5

Japanese gun (county). Format for interchange is the JCG reference number for the gun from JARL list: five numeric digits including any leading zeros. N.B.: JARL’s internal numbering scheme for prefectures differs from ISO 3166-2.

LOCATION

C

N

 

64

Geographical location[6]of the station. E.g., “Summit of Mt. Mitchell”, “Santa Catalina Island”, “Parque Nacional  Torres del Paine”

MAILING_ADDRESS

M

N

 

256

Postal Mailing address to contact this station; should be internationalized

NZ_COUNTY

E

N

Sub_Gov2

5

New Zealand county. Format for interchange is the NZ county as enumerated in FIPS Pub. 10-4. Note: this FIPS PUB has been withdrawn and iwill be replaced with ISO 3166.

OPERATOR

C

N

 

15

Operator of the station given in CALL field of the tSTATION record. Typically this field would be used for a guest operator or multiple operators using a single call sign. Call sign is insensitive to case. Legal value for call sign characters are [A-Z0-9/].

POSTAL_CODE

C

N

 

10

National postal code (for use as an awards counter).

REC_TYPE

E

Y

 

10

Always "tSTATION". This declares the record to be a Trusted Station record.

REPEATER[8]

C

N

 

15

Call sign of terrestrial repeater used in making this contact. Call sign is insensitive to case. Legal values for call sign characters are [A-Z0-9/].

RIG

M

N

 

256

Description of radios, antennas, ancillary equipment, etc.

SAT_MODE[7]

E

N

 

5

Format for interchange shall be the designator for satellite transponder mode, e.g. A, B, J… If the SAT_MODE field is present, the SAT_NAME  field shall also be present. See Table 7 for legal values of the enumeration.

SAT_NAME

E

N

 

5

Format for interchange shall be the designation of the satellite used in upper case (RS-10, AO-10, FO-20, etc.). See Table 7 legal values of the enumeration.

SDOK

C

N

 

8

DARC Sonder-DOK. Distinctive (or “special”) DOK, for special events, is a string of up to 8 characters (see DARC  list, frequently updated)

SK_DISTRICT

E

N

 

3

Slovak district (“okres”). Interchange format is a three letter abbreviation; consult list from CRC for the legal values of the enumeration.

SUB_GOV1

E

N

Sub_Gov1 

6

The top-level administrative subdivision of a country as specified in ISO 3166-2:1998. The SUB_GOV1 subdivision might be a State (USA), a Province (Canada; Spain), an Oblast (Russia), a Canton (Switzerland), a County (Great Britain; Ireland), a Prefecture (Japan), etc. The enumeration of this subdivision shall be as given in ISO 3166-2.

In instances where no administrative subdivision is specified in ISO 3166-2, the administrative subdivision and its enumeration listed in  FIPS Pub. 10-4 may be substituted, if one exists. An enumerated value from FIPS Pub. 10-4 is distinguishable from an ISO 3166-2 enumerated value by the absence of a hyphen (‘-‘)  in the FIPS Pub. 10-4 enumerated value and the presence of a hyphen (‘-‘)  in the ISO 3166-2 enumerated value.

SUB_GOV2

C

N

 Sub_Gov2

64

The administrative subdivision that is “subordinate” to  the subdivision in SUB_GOV1. Examples of SUB_GOV2 are a County/Parish (USA), a Gun (Japan), a City (Japan), etc. The value of SUB_GOV2 is a non-enumerated character string that shall be treated as case insensitive. If a record contains the field SUB_GOV2, then the record shall also contain the filed SUB_GOV1. One or more fields of category Sub_Gov2 may appear within a single record.

SUB_GOV3

C

N

 Sub_Gov3

64

The administrative subdivision that is “subordinate” to the subdivision in SUB_GOV2. Examples include Municipality (Chile), City, Town ,Village, etc. The value of SUB_GOV3 is a non-enumerated character string that shall be treated as case insensitive. If a record contains the SUB_GOV3 field, then the SUB_GOV1 field shall be present and one or more fields of category Sub_Gov2 may be present in the record. One or more fields of category Sub_Gov3 may appear in a single record.

STATION_TYPE

E

N

 

12

See Table 8 for legal values of the enumeration.

STATION_UID

I

Y

 

2

This is a two digit (locally) Unique ID (UID) of this tSTATION record. Unique within a GAbbI logical file.

TX_PWR

F

N

 

8

Transmitter power. Format for interchange shall be transmitter output power in watts (W) with no greater than 1 mW precision. A decimal point shall be included. There shall be no leading zeros; there shall be no trailing zeroes after the last significant digit. 

URL

C

N

 

256

Universal Resource Locator (URL) that will provide further information on this station. 

US_COUNTY

E

N

Sub_Gov2

5

US County. The value is a five (5) character  code composed of the two-letter state alpha code from FIPS Pub. 5-2 (now withdrawn) followed by  the three digit numeric code for the county (or independent city) from FIPS Pub. 6-4 (now withdrawn). E.g., Autauga County, Alabama is represented as AL001 and Apache County, Arizona is represented as AZ001. For stations located on a county line, two instances of the US_COUNTY  field may appear within a tSTATION or tCONTACT record.

WAE

E

N

 

3

Worked All Europe entity. Three digit numeric identifier from DARC WAE list

Common Fields

This field is common to all record types. The field is identical both in its name and its meaning to more than one record type. 

Name

Type

Required

Max Size (chars)

Description

REC_TYPE

E

N

15

This defines the type of record. The default is QSO record

4. File Definition

Record Types

Record 

Description

tCERT

Identity certificate. This record shall be placed in the header area preceding  the <eoh> tag. 

tCONTACT

This record contains the unique information describing a QSO. All tCONTACT records shall be in the data area, following the <eoh> tag. 

tHEADER

This indicates a logical header record. This record shall be placed in the header area preceding the <eoh> tag. 

tSTATION

This record contains the common information describing a series of QSOs. Typically, this is information that describes the sender and his/her station. All tSTATION records shall be placed in the header area preceding the <eoh> tag. 

QSO

This is also the standard logbook format. All QSO records shall be in the data area, following the <eoh> tag. To maintain backward compatibility, this is the default record type.

Categories

Implicit rules are associated with some fields; at least one extra parameter (in addition to Type, Signed, Required & Maximum Size) must be provided in order to specify fields that fall into these categories: 

Name

Super-Category

Sub-Category

Parameters

Sub_Gov2

Sub_Gov1

Sub_Gov3

If a field  in the Sub_Gov2 category is of Enumeration (E) type, a list of the enumerated values shall be provided. Each enumerated value for a field  in the Sub_Gov2 category shall be associated with an enumerated value in a field of the superior category (Sub_Gov1). 

Sub_Gov3

Sub_Gov2

or

Sub_Gov1

If a field  in the Sub_Gov3 category is of Enumeration (E) type, a list of the enumerated values shall be provided. Each enumerated value for a field  in the Sub_Gov3 category shall be associated with an enumerated value in field of a super-category (Sub_Gov2 or Sub_Gov1). 

Signature

A specific signing rule (which fields are signed; in what order do fields appear) must be specified.

Sub_Gov1, Sub_Gov2 & Sub_Gov3

The fields which describe administrative subdivisions constitute an implicit hierarchy beginning at the level of DXCC entity:

+---DXCC|
     +---Sub_Gov1
            |
            +---Sub_Gov2
                   |
                   +---Sub_Gov3

If a GAbbI writer specifies the value for a field from the "Sub_Gov" hierarchy, the writer shall also specify a fully consistent set of values for all the superior fields in the hierarchy up to and including DXCC entity.

A reader shall treat the appearance of a single field from the "Sub_Gov" hierarchy as an implicit specification of a value for each of the superior fields in the hierarchy up to and including DXCC entity. E.g.US_COUNTY == HI001 (Hawaii County) should be interpreted by a reader as specifying SUB_GOV1 == US-HI (State of Hawaii) and DXCC == 110 (Hawaii) in addition to the county; and JP_CITY == 2701 (Kobe) should be read as specifying SUB_GOV1 == JP-28  (Hyôgo Prefecture) and DXCC == 339 (Japan) in addition to the city. When more than one field in the "Sub_Gov" hierarchy appears in a record, the values specified implicitly and explicitly at every level of the hierarchy shall be identical. In the event an inconsistency amongst the fields of the "Sub_Gov" hierarchy is detected, the reader shall issue an error message and may discard the record.

The values of the SUB_GOV2 and SUB_GOV3 fields  are non-enumerated character strings. Enumerations for administrative subdivisions below the top-level are typically not found in standardized sources such as ISO 3166-2 and FIPS Pub. 10-4. Field which are members of category Sub_Gov2 and category Sub_Gov3 and which have an enumerated field value shall have a uniquely distinguished field name that shall begin with the ISO 3166-1:1997 alpha-2 (two-letter) code element followed by an underscore ("_").

GAbbI Sample File


[1]Illegal characters encountered while scanning a field are to be ignored. The field length shall be interpreted as the number of valid characters to be read. If while scanning a field, the reader encounters an illegal character other than an end-of-line character (<CR> or <NL>), the reader shall issue a warning. If a start of field delimiter ‘<’ is encountered before the expected end of field, the reader shall reject the field being read and issue a warning. 

N.B.: GAbbI is only weakly armored against line folding and provides no protection at all against gratuitous character re-mapping that can be introduced by the transport layer, especially e-mail. A prudent precaution would be to encode a GAbbI object using base64 prior to transport via e-mail. This encoding is mandatory if UTF-8 characters beyond the 7-bit ASCII character set are to be exchanged. 

[2] To indicate a cross-band contact the pair of fields: BAND_RX and BAND_TX shall be used. If the BAND field appears in a record then neither BAND_RX nor BAND_TX may appear. If either the BAND_RX or BAND_TX field appears, then both fields must appear. 

[3] To indicate a split-frequency contact the pair of fields: FREQ_RX and FREQ_TX shall be used. If the FREQ field appears in a record then neither FREQ_RX nor FREQ_TX may appear. If either the FREQ_RX or FREQ_TX field appears, then both fields must appear.  All cross-band contacts are split-frequency; not every split-frequency contact is crossband.

[4] To indicate a cross-mode contact the pair of fields: MODE_RX and MODE_TX shall be used. If the MODE field appears in a record then neither MODE_RX nor MODE_TX may appear. If either the MODE_RX or MODE_TX field appears, then both fields must appear. 

[5] A compliant GAbbI reader shall support SHA-1 message digest and RSA signatures. Readers may optionally support the MD5 message digest and/or DSA and ECDSA signatures. The GAbbI header declarations cue the reader on which algorithms will be used in the file. Which combination of digest and key type were actually used for a given signature is implicitly specified via the SIGN_XXX family of fields on a signature-by-signature basis. If a reader is presented with data signed using a public key algorithm that the reader does not support, the reader shall generate a fatal error. 

[6]”Geographic location” should not correspond to a specific governmental or administrative subdivision such as a  town or village. Location within an administrative subdivision should be indicated by use of one or more “SUB_GOV#” fields. 

[7] If needed for an explicit declaration, the non-callsign value of "NONE" for REPEATER shall be permitted. 

[8] Setting SAT_MODE equal to  "EME" shall indicate an Earth-Moon-Earth (moonbounce) contact. The corresponding SAT_NAME shall be "MOON".