5.7 Keyword Domains

  Keywords that are not required or reserved for the standard FITS structures might easily have different meanings for different groups. Thus, the significance of a keyword would depend upon the context. The FITS community has looked for possible ways to define domains that would identify which keyword definitions apply. The initial approach to defining keyword domains was the concept of keyword hierarchies. In this method, syntax in the FITS file would indicate that certain keywords were to be considered as part of a named domain. Such domains might exist in a hierarchy of levels. For example, the highest level might be a particular institution, and lower levels could be individual projects within the institution. However, consensus about what the structure should be appears unlikely.

The reasons for the lack of agreement become apparent from an examination of the principal approaches. One approach would use the string ``HIERARCH'' in columns 1-8 of a header card image as domain indicator. Domain names, at progressively lower levels, would follow in sequence in the card image, and, finally, the keyword=value statement would appear after the lowest level domain name. Critics of this approach argue that the HIERARCH keyword and the domain names would leave little room on the card image for the actual keyword and value information, or for comment fields. Also, many FITS readers would be looking in columns 1-8 to find the keyword, and the keywords behind HIERARCH would be inaccessible. Special parsers would need to be built.

The other approach would use a ``KHBEGIN '' keyword to signal the beginning of a domain; the value would be the domain name. Subsequent keywords, beginning in column 1, would have the value for that domain. A ``KHEND   '' keyword would signal the end of a domain. Domains could be nested. Within the domains, keywords would begin in column 1, as do the other FITS keywords. Critics of this approach argue that the placement of the low-level hierarchical keywords in columns 1-8 would mix them with other simple nonstandard FITS keywords, existing FITS readers might generate incorrect results, and special code would be needed to interpret the keywords properly.

The difference between these two approaches is not just a matter of detail; it is the principle of whether keywords restricted to a particular domain should appear in the first eight columns of the card image or should start in a later column. Because this issue has not been resolved by the FITS committees and resolution does not appear imminent, do not assume that FITS readers will recognize either scheme. For that reason, neither approach is discussed further in this document.

Some installations have implemented a convention similar to the HIERARCH proposal in which a keyword without values, such as HISTORY (or even HIERARCH) appears in the first eight columns, followed by one or more domain names and then the keyword. The ESO Archive, for example, uses HIERARCH. The first sample FITS header in the first FITS paper (Wells, Greisen, and Harten 1981) illustrated this approach, but it was not formally proposed or tested for interoperability at the time. If a group chooses to use such a convention, the header should always allow a reader unfamiliar with it to interpret those card images as pure comments. An example of such usage appears in Example 1 of Appendix A.

Existing constructs in FITS provide another approach to domain definition. Some reserved FITS keywords--for example, ORIGIN, TELESCOP, and INSTRUME--describe natural domain limiters, the installation where the FITS file was written and the telescope and instrument used to obtain the data. Keywords following an ORIGIN keyword in an HDU could be understood as having the meaning defined for the particular installation given by the value of the ORIGIN keyword; similarly TELESCOP and INSTRUME, when present, could signify that keywords following have the meaning defined for data sets from the telescope and/or instrument named. It is then possible to define keyword meanings specific to a particular organization, telescope, and/or instrument and use the values of the relevant keywords to signify that such a particular set of keyword definitions applies. In this way, even though a particular keyword might be used differently in different contexts, the applicable context could be identified.

The same problem can arise in naming table column headers as when choosing keyword names: different groups may use the same column headings with different meaning. Again, some method of defining project-specific meanings for the table headings is needed. The proposal to use the ORIGIN, TELESCOP, and INSTRUME keywords as domain limiters works here, too. These keywords could be either in the primary header of the file or the individual extension header. Including these keywords in the extension headers has the disadvantage that they will be repeated from header to header, using extra space, but it has advantages: the domain indicators appear as keywords in the same header as keywords giving the column labels they describe, and they will remain associated with the table, should for some reason the table but not the primary header be copied from the FITS data set to another, say, to a data set with a different primary header. The additional information gained by including domain keywords in each extension thus appears worth the small extra overhead.

One possible problem that has been suggested for this approach is that some local software systems might rearrange keyword order when reading the FITS file into an internal format structure and so lose the domain information. If this approach is used, keyword order should not be critical.

Because they are used in domain conventions, use of the keywords HIERARCH, KHBEGIN, and KHEND for other purposes is discouraged. All keywords with important information must appear in columns 1-8.