2

GENERAL GUIDELINES

2.1

General Information

2.1.1

Following the rules

Data creators: The guidelines in this document are intended for content creators for the Getty Vocabularies, including Getty Vocabulary Program editors, translating projects, and other contributors. To create or edit data for the Getty Vocabularies, read the discussion and follow the editorial RULES for each field. Contributors or other users may compare their in-house rules to the guidelines in this document to gauge compatibility. Where the rules or their application are ambiguous or not applicable to a situation at hand, please consult with the Getty Vocabulary Program, vocab@getty.edu. These rules are regularly updated to reflect solutions and recommendations for new issues.

2.1.2

Required fields and minimal records

Implementers: Developers and other implementers of the Getty Vocabularies should refer to this document to extrapolate information that will aid in understanding and presenting the Getty Vocabulary data correctly and as intended.

Among the most important guidelines for implementers are the following:

• Do not omit references to the sources and contributors of the Getty Vocabulary data. The Getty Vocabularies are compiled from contributors' data and this contribution should be recognized. Published sources should be cited to avoid plagiarism.
• In implementations, please consider including all data included in the Vocabulary concept record ("record" meaning all data linked directly or indirectly by a given subject_id).
• Do not omit numeric identifiers for the data in displays to end users; particularly importat are the subject_id and the term_id.
• Do not omit flags such as "unknown" or values in display fields "undetermined." For researchers, scholarship, contributors who are adding information to the records, and others, it important to know when a value is unknown rather than left empty. An empty field means nothing. A value such as "unknown," even if it is a default value, is in itself useful information about the status of the field and can serve to identify areas requiring additional research. See also the discussion below about how catalogers deal with information that is unknown to themselves, or unknowable in the broader context of scholarship.

VCS: The custom-built editorial system used by the Getty Vocabulary Program is called "VCS" (Vocabulary Coordination System). We have tried to eliminate reference to this system, because these guidelines are system-neutral; however, you may find legacy occasional references to "VCS" in this document. The Vocabulary databases in which the contributions are compiled and edited comprise relational tables and allow construction of rich data in compliance with international standards for thesauri (ISO and NISO). In addition to creating polyhierarchies, linking associative relationships, creating terms and other data in multiple languages, and other typical funtions required by a thesaurus-construction system, the Vocabulary Program system is optimized for loading contributions, merging contributions representing the same concept, citing preferences to allow alternate points of view, and tracking revision histories over long periods of time.

2.1.2.1

Minimal record
When adding new records, create a record that meets requirements for a minimal record, which contains at minimum all required fields ("core" fields).

2.1.2.2

Fuller records
Records that are fuller than "minimum" are welcome, particularly those having useful alternate names, relationships, and coreferences. Editors: When adding records or editing existing records, you may create a fuller record as warranted by priorities and avaialble time.

2.1.2.3

Required fields
Each record must include a term and a position in the hierarchy. A scope note is also required for all new records:

• a numeric ID identifies the record uniquely (Subject_IDs are assigned by the system)
• a parent (create the link to a parent by designating the correct level where the new record should be added or moved)
• "preferred term" for the concept record, which is a default term used to create displays and to provide a consistent choice for end users who wish to use the AAT as an authority in this way (the Descriptor in English is the minimum requirement for "preferred term"); for translations, there must also be a "preferred term" in the language of translation.
• [Alternate Descriptor, where mandated; see Guidelines; if the Descriptor is a plural noun, the singular form of the noun usually must be included as an Alternate Descriptor]
  

For each Term
• various associated flags (generally automatically assigned; examples are Historical or Current)
• sources for the term (published or common usage sources are cited)
• language of the term
• contributor of the term (a term may be contributed by multiple contributors, who will all be cited as contributor)

For the Scope Note
• sources for the scope note
• language of the scope note
• contributor of the scope note
  
  
• Additional fields, including the Associative Relationships, are welcome and included as time and editorial priorities allow.

2.1.3

Format and values

• Examples in the various sections of the editorial rules illustrate the format of data in all fields.

2.1.3.1

Controlled vocabulary in concept records
Some fields in the Getty Vocabulary concept records are themselves restricted to values coming from separate controlled vocabulary. This means that you must link to a value in a controlled list. The lists are extensible; additional values are added as needed. Controlled vocabulary in the AAT concept record includes dozens of short controlled lists for flags, as well as long lists such as Language, Relationship Type, or Sources.

2.1.4

Capitalization and abbreviation

• In general, data in all fields should be expressed in mixed case (i.e., with the appropriate initial capitals).
  
  NOTE: For most languages, terms should nearly always be expressed in lower case (e.g., oil paintings in English), except where the normal rules for a given language contradict this rule (e.g., Ölgemälde in German). Follow normal exceptions for capitalizing the initial letter in a given language, including terms containing proper names (e.g., Indiana limestone in English)and the names of styles (e.g., Impressionism in English). For terms, do not use all caps, except for abbreviations (e.g., LED for light-emitting diode). See further discussion under Terms fields below.
  
  
• Avoid abbreviations in all fields unless so-established by common usage as warranted by sources, or as otherwise instructed in the appropriate editorial rules.
  
  For terms, generally avoid abbreviations in the preferred term, but if there is a common abbreviation, include it as a variant term (UF term) to allow retrieval. There may be exceptions when the most commonly used term for the concept is an abbreviated version.

2.1.5

Language of the Record

2.1.5.1

Multilingual
The default language of AAT is American English. However, the AAT is multilingual because the terms may be flagged and hierarchies may be constructed in multiple languages. Scope notes may be translated into multiple languages. Differences in languages as spoken in different places may be noted, as the difference between American English and British English, or between Standard French and Canadian French. The field tags, many flags, and other information in the AAT record are expressed in American English by default; however, users could translate these items in other languages as necessary for regional or local displays.

Background: In a completely multilingual vocabulary, all languages would be treated equally, with none serving as a so-called dominant language. However, in practical applications, it is often necessary to treat one language as the default dominant language, particularly when the vocabulary is rich and complex. An example is the AAT, in which each concept record includes over 100 fields or data elements in addition to the terms themselves. With such vocabularies, it would be impractical to maintain the data values of flags, notes, dates, hierarchies, and other subsidiary information in several languages in the master AAT data files. Thus for the AAT, English is the dominant language, although terms and scope notes may be in multiple languages in the master database. In addition, if every term in the original source language has not been assigned equivalents in all other target languages, the status of the other languages is not equal to that of the source language, and they are technically known as secondary languages. As more and more contributions are compiled in AAT, critical mass is reached to allow displays by implementers in various languages.

2.1.5.2

Alphabet
Terms, scope notes, and other fields are expressed using Unicode. If terms or scope notes are contributed in a language other than English or in an alphabet or writing system other than the Roman alphabet, an English translation in the Roman alphabet must also be included.

2.1.5.3

Diacritics
The AAT is published in Unicode. However, in legacy AAT data special codes may used to represent diacritics (e.g., berg$02eres contains the accent grave code for bergères).

• See the diacritical codes listed in Appendix A. The codes comprise a dollar sign and two or three digits; the codes are usually placed before the letter requiring the diacritic.
  
  
  • Example
    [terms with accents graves in display]
    
  • bergères (preferred, English-P, French-P)
    bergère (alternate descriptor)
    barjaires
    barjairs
    bergère chairs
    bergiers
    birjairs
    bujairs
    burjaires
    burjairs
    cabriole bergères
    chairs, bergère
    fauteuils à panneaux
    fauteuils en bergère
    

2.1.6

Production goals

• Emphasis is placed on accuracy and consistency, where possible. The Getty Vocabulary Program strives to process and publish contributions in a timely manner. To this end, editorial standards and decision trees are utilized. For example, Vocabulary Editors are assigned quotas for the number of records that they should complete each week. The quota differs depending upon the editorial task. Contributors with local vocabulary projects may wish to adopt similar rules.
  
  

2.1.7

Leaving records unfinished

• Contributors supervising vocabulary projects should avoid introducing unfinished records into the submitted data files. We advise that records under construction be maintained separately from records that are ready for submission, or that other checks are in place to avoid submitting unfinished data.

2.1.8

Quality control

• Avoid typographical errors. Editors should proofread their work carefully.
  
  
• Pay special attention to spelling of Terms, because they are the most important part of the AAT record, yet the most difficult in which to spot errors.

2.1.9

Avoid plagiarism

2.1.9.1

Published sources
CAVEAT: For data in AAT records, do not copy texts from published sources verbatim! Read, analyze, and rephrase the material. Do not jump to conclusions or state more than is discussed in your sources.

• If you extract texts from the Web or another source, do so only as a reference. You must rewrite any such text and cite the source.
  
  
• Avoid pasting illegal non-Unicode characters into your data files. Do not include non-Unicode MARC characters or other scripts or characters outside the Unicode standard.
  
  
• It is required to cite the published source of terms and the information in notes. In the Page field, include the page number, URL, or other appropriate reference to the passage where you found the term or other information.
  
  
• There are three places in an AAT record to record the source. Sources may be linked directly to each Term and to the Scope (Descriptive) Note. For other information, record the source in the overall Subject citation designation.

2.1.9.2

Contributors
It is required to include the contributor who provided Terms and the Scope (Descriptive) Note. A contributor should include this information in the prescribed spreadsheet. When processing contributed data, the Vocabulary Program strives to avoid misrepresenting the contribution. However, note that other contributors may add data to the original contributed record. Final editorial control lies with the Getty Vocabulary Program (as agreed to in the Data Contribution and License Agreement for Contribution).

2.1.9.2.1

What is a contributor?
A contributor to the Getty Vocabularies is an institution, scholarly project, or occasionally an individual scholar or other expert (such as a tribal expert). Most contributors use programmers who process data files that originated in their institution. They send their data to the Vocabulary Program in a prescribed format (currently, this is the prescribed spreadsheet). At Getty, the spreadsheet is transformed into our XML contribution format for loading in the VCS editorial system. Contributors may also use our online contribution form, where they fill in data, one record at a time. The contribution form provides appropriate controlled values and validates the format to produce the appropriate XML data for loading. Occasionally, as a third option, contributors may send a term or two in an email, and a Vocabulary Program editor may add the data by hand to VCS.

2.1.10

Expressing uncertainty and ambiguity

• Accuracy: Uncertainty and ambiguity is inherent in cultural heritage information. Clearly expressing this information is critical for data quality and user confidence in the Getty Vocabularies. Below are rules regarding a few common misrepresentations or mistakes in new data.
  
  When information is described as uncertain or debatable by your source, the information may still be recorded, but with an indication of uncertainty or approximation in a text field, such as the Scope (Descriptive) Note or "Display Date" note field (e.g., include the words "ca." or "probably").
  
  
• The cataloger or editor is rarely a recognized expert in the content. Thus, you should be careful to never express more certainty than warranted by your sources. Do not make assumptions: your own experience, knowledge, or point of view is probably not the only option. Rely upon established sources and verify broadly across several sources and across cultures.
  
  If there is disagreement among reliable sources, use terms such as probably or otherwise express the uncertainty (e.g., "Some scholars believe there is a relationship between Aterian leaf-shaped blades and Solutrean blades, and that the Aterians entered the Iberian Peninsula during Solutrean times."). Consider idiosyncrasies of published sources or contributed data (where data may have been parsed incorrectly by algorithm out of various systems). Analyze what is agreed upon by experts as true and what is recognized as only possibly or probably true.
  
  
• Index for retrieval. Index important information found in a text field, such as the Scope Note or Display Date field. Use appropriate indexing fields and estimate how to choose data for retrieval. See the discussion of how to do this at the individual Display Date and Scope (Descriptive) Note fields below.

2.1.11

Uncertainty and ambiguity in indexing fields

• Indexing fields are intended for retrieval. Any fields that contain a controlled number (e.g., Start Date), values controlled by pick lists (e.g., Preferred flag), or links to controlled lists (e.g., Language) are indexing fields. Consider retrieval issues when you assign terms and values to indexing fields.
  
  
• When fields do not display to end-users: Some indexing fields do not display to end-users. For example, the Start Date and End Date should not display to end-users; for these fields, estimate a span of time as broadly as can be applicable. Estimating too narrowly will result in failed retrieval. However, estimating overly broadly will result in false hits or failure in retrieval.
  
  
• When fields display to end users: Although there are exceptions as noted above, most fields in the AAT are displayed to end users. If the end user can see the field, employ the following strategies: Do not make overly broad estimations or guesses. However, if a specific value is uncertain, use a broader value, or use both of two possible values, depending upon the circumstances. For example, in the Scope Note, if sources disagree about whether a characteristic developed in 15th-century Bruges or in Brussels, for indexing this information, you could 1) state that the concept was the broader Flemish (encompassing both Bruges and Brussels), or 2) name both cities for indexing, stating in the Scope Note that scholars disagree regarding if the concept developed in Bruges or Brussels.
  
  
• Knowable information: For information that is knowable but simply unknown by you, always use a more general, known to be correct term, or omit the information. When information is ambiguous due to your own lack of information regarding the issue, do not use terms such as "probably" or "perhaps" because this implies that scholars are uncertain of this information (rather than what is true, that in your opinion or experience it is uncertain).
  
  
• Debated information: For information that is unknowable because scholars disagree, or because the historical or archaeological information is incomplete or interpretation of the information is debated, you may use terms such as "probably" or "perhaps" to explain the ambiguity or uncertainty in a Display Date or Scope (Descriptive) Note.
  
  
• Flags: For flags or other fields, where you must choose only one value to index, make the best choice based on the information at hand. Document your decisions so you and others working on the project will be consistent. See further discussion of individual fields in the relevant chapters.

2.1.12

Uncertain terms for a concept

• When should you include two terms as synonyms in the same concept record, or when should you instead create two separate records for the two terms? In some cases, scholarly opinion or common usage may be divided regarding whether two terms refer to the same concept. For both terms to appear in the same AAT concept record, the Scope Note should encompass the meaning of both terms equally. Most importantly, it should be appropriate to use the terms interchangeably. If one term is appropriate in only some cases, then these are not true synonyms. Commonly, mistakes occur when two terms are in the same record, but one term is actually an example of or special case of the other term. Another common mistake is when the Scope Note is written too broadly or too narrowly to properly apply to both terms. For example, this happens when an editor has an example of an object to which the term is applied, and they assume that the term is narrowly applicable to only that object; maybe the same term is applicable to another variation on the object, found perhaps in another culture. Either the Scope Note or the choice of the two terms in the same record is in error.
  
  If the terms are not true synonyms, place them in separate records, and note the possible connection in Scope (Descriptive) Note and through an Associative Relationship.

2.2

Merging records

• If two records are contributed for the same concept, they must be merged. The Vocabulary Program or approved surrogates may "merge" multiple records that represent the same concept. In the Vocabulary Program, the merging is done automatically via algorithm in the loading process, or for less obvious matches, it is done by editors by hand in VCS.
  
  
• In the merged record, the contributors' Brief Name appears with the Terms and Scope (Descriptive) Note that they have contributed. Other fields in the AAT data do not link to the contributor name.
  
  
• Caveat: Note that when you merge two records that have children in the hierarchy, all of the children will be combined in a list under the newly merged record. You must check to see if any of the children in the new list should themselves be merged.

2.2.1

Rules for merging

2.2.1.1

When to merge

2.2.1.1.1

Matching the term, parents, and meaning
Before merging, it must be ascertained that the two records actually represent exactly the same concept. The AAT concepts to be merged must contain a term that is the same, and they must have the same definition and scope as described in the Scope (Descriptive) Note.

• Terms: Terms must be Descriptors, Alternate Descriptors, or Used For Terms for the same concept (including synonyms, terms in different languages, and occasionally historical terms). Note that there may be separate concepts known by very similar terms in the AAT; do NOT merge records unless their meaning is identical.
  
  
• Caveat re. merging: If in doubt, do NOT merge the records!

2.2.1.1.2

Facets
Do NOT merge facets.

2.2.1.1.3

Tops of Hierarchies
Do NOT merge records flagged with Record Type "hierarchy name."

2.2.1.1.4

Guide terms
In general, do not merge terms with record type "Guide Term" (these phrases display with angled brackets in publication). The only reason to merge Guide Terms is when you wish to combine all the children of two Guide Terms into one set of siblings.

2.2.2

Procedures for merging

• After determining that the records absolutely represent the same concept, you may "merge" by indicating the best primary record as "Dominant record" and the record(s) that are "Recessive records" to be merged into it. You should always choose the older record as the Dominant record if the data has been published. Reason is, this is a record that more users have likely linked to. For consistency and reliability of the data for end users, you must strive to keep subject_ids persistent over time. Implementers have access to subject_ids that have been deprecated due to having been Recessive in a merge; however, we must keep the inconvenience of dealing with this situation to a minimum.
  
  
• Mark list: Before every merge, it is mandatory editorial practice to review which records you will merge. In VCS, there is a Mark List window where editors may double-check that they have marked the correct records, and only the correct records, as Dominant and Recessive prior to a Merge.
  
  
• After merging, check the merged record and edit as necessary. Allowing an incorrectly Merged record to be published and used over time is a grave problem.
  

2.2.2.1

Unmerging
If, in spite of all precautions, you mistakenly merge the wrong records and you notice this error immediately, you should be able to perform an "unmerge" (this is a function in VCS). If some time has passed before you've noticed the mistake, unmerging may have to be done in stages, and with great care.

2.3

Moving records

2.3.1

Rules for moving

2.3.1.1

When to move records
In the Getty Vocabularies editorial process, "moving" is done in order 1) to put candidate records in the publishable parts of the hierarchies or 2) to update the subdivisions of a hierarchy.

2.3.2

Procedures for moving

• Determine where in the hierarchy the records belong, based on the rules in Chapter 3.1 Hierarchical Relationships. In a hierarchy view, mark the intended parent (broader context) record as "Dominant" and the record(s) that are to be moved under it as "Recessive". Double check the records you have marked as Dominant and Recessive, and perform the Move function. In AAT, it is advised to use a method such as this for Move, rather than drag-and-drop or another means; reason is, the AAT hierarchies are so dense and long, it is difficult to keep track of the records being marked for Move with drag-and-drop, etc.
  
  
• Mark list: Before every Move, it is mandatory editorial practice to check what is marked for moving.
  
  
• After moving, check the hierarchy to be sure that the move was accomplished as you intended.

2.3.2.1

Undoing a move
If, in spite of all precautions, you mistakenly move the record(s) incorrectly and you notice this error immediately, you should be able to "Undo Move". If time has passed before you have noticed the mistake or if you have done any other editing, you will likely have to correct the hierarchy manually.

2.3.3

Comments on Revision History
Common actions, including loading records, creating new records, editing terms and scopenotes, adding associative relationships, moving, and others are automatically recorded in the Revision History for the AAT record.

In the AAT Revision History, we flag the most important changes, where the automatic Revision History alone is not adequate for implementors and translating projects to distinguish minor from major edits. The editor manually makes a comment in the Note field attached to the Revision History action that was taken on a certain date. The Note text is Preceded with "NB:" (for Nota Bene). For example, if an editor makes a significant change to a Scope Note, that changes the meaning and will require translating projects and other users to edit or reconsider their own Scope Notes: NB: Changed scope to broader meaning, was too narrowly defined. Implementers and other users are advised to regularly refer to the AAT Revision History for new "Nota Bene" indicators.

2.4

Sample Records

2.4.1

Sample AAT record

• The record below is presented in an arrangement suitable for end users.

2.4.2

Sample AAT record in VCS

• The record below is a sample from the VCS editorial system.

2.5

List of Fields

2.5.1

About the fields

• There are around 90 "fields" of information in an AAT record. It is unlikely that all fields of information will be available or appropriate for all concepts. However, certain information is considered "core," and is required for each minimal AAT record (see also Required fields and minimal records above).
  
  
• For some required fields, the system provides a default value, which means that this value will be used in that field unless you change it.
  
  
• In VCS and advised for other systems: Some fields are display-only fields that are controlled by the system. For example, the Subject_ID may not be changed by the editor. In AAT, it is supplied by the system according to rules in the VCS program.
  
  
• To view the Data Dictionary, see Addendum Z.

2.5.2

List of VCS Fields^[1]

3.1 HIERARCHICAL RELATIONSHIPS
    Parents (required)
    Historical Flag (required-default)
    Dates for relationship to parents
    Parent string (required-default)
    Relationship Type (required-default)  

3.2 IDENTIFYING NUMBERS, STATUS FLAGS, AND SUBJECT SOURCES
    Subject ID (required-default)
    Parent Key (required)
    Merged Status (required-default)
    Published Status (required-default)
    Review Status (required-default)
    Record Type (required-default)
    Candidate Status (required-default)
    Label (required-default)
    Contributors for Subject Record (required)
    Sources for the Subject Record (required)

3.3 TERMS
    Term ID (required-default)
    Term (required)
    Preferred Flag (required-default)
    Qualifier
    Sequence Number (required-default)
    Historical Flag (required-default)
    Term Type (required-default)
    Part of Speech (required-default)
    Vernacular Flag (required-default)
    Language for Terms
    Language Status (required-default)
    Contributor for Term (required-default)
    Preferred Flag for Contributor (required-default)
    Sources for Terms (required)
    Page Number for Term Source (required)
    Preferred Flag for Source (required-default)
    Dates for Terms
    Display Term Flag (required-default)
    AACR Flag (LC heading)
    Other Flags
    Assigned To

3.4 SCOPE (DESCRIPTIVE) NOTE
    Scope (Descriptive) Note (required for Concepts)
    Sources for the Scope (Descriptive) Note (required for Concepts)
    Contributors for the Scope (Descriptive) Note (required for Concepts)
    Language for Scope Note (required for Concepts)

3.5 ASSOCIATIVE RELATIONSHIPS
    Related Concepts
    Relationship Type
    Historical Flag
    Dates for Associative Relationship

[In the AAT Guidelines, there are no sections 3.6 and 3.7]

3.8 ADMINISTRATIVE FLAGS, NOTES, AND REVISION HISTORY
    Comment Flag
    Problem Flag
    Assigned To
    Special Project
    Facet
    Legacy ID
    Class Notation
    Image
    Index Note
    Not Found Note
    Status Note
    Editor Note
    Revision History (required-default)

^[1]Required default indicates that a default is set by the system, but should be changed by the editor as necessary (and if possible). Some fields, such as Subject_ID, cannot be edited.

Updated 15 August 2024
Document is subject to frequent revisions