2

GENERAL GUIDELINES

2.1

General Information

2.1.1

Following the rules

Data creators: For Vocabulary editors, contributors, and other content creators, to enter or edit data for the Getty Vocabularies, follow the Editorial Rules in this document. 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.

Among the most important guidelines 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 record ("record" meaning all data linked directly or indirectly by a given subject_id). Do not omit flags such as "unknown" or values in display fields "undetermined." For scholarship, contributors who are adding information to the records, and others, it useful 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). You may find occasional references to "VCS" in this document, for the benefit of Vocabulary Program editors or others using this particular system. The Vocabulary databases comprise relational tables and allow construction of rich data in compliance with international standards for thesauri. 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, VCS 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
For contributions, fuller records are welcome, particularly those having useful alternate names, relationships, and coreferences. Editors: When adding records or editing existing records, if there is additional time and the place is important, you may create a fuller record by filling in fields beyond the Core as time and research warrant.

2.1.2.3

Required fields
Each record must include a name, a place type, and a position in the hierarchy. The VCS will not allow you to save a record without the required fields:

• a numeric ID identifies the record uniquely (IDs are assigned by the system)
• a parent (you create the link to a parent by designating the correct parent by the mark "DOM" (for dominant) when you create or move a record)
• preferred name
  • various associated flags: current/historical, vernacular/other, noun/adjective, display/index flag, etc.
  • source(s) for the name
  • language, if known
  • contributor of the name (automatically assigned by VCS)
• place type(s)
  
  
• Other fields are strongly recommended:
  • coordinates
  • variant names
    
    
• Additional fields, including the Descriptive Note, may be 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
Some fields use controlled vocabulary, meaning you must link to a value in a controlled list. If you feel additional values need to be added to the list, consult with your supervisor. Controlled vocabulary includes dozens of short lists for flags as well as long lists, such as Language and Place Type.

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 for proper names, but not all upper-case or all in lower case), unless otherwise indicated. Use initial capitals for names. See further discussion under each field below.
  
  
• Avoid abbreviations in all fields unless otherwise instructed in the appropriate rules. For names, avoid abbreviations in the preferred name, but include important abbreviations in variant names to allow retrieval.

2.1.5

Language of the Record

2.1.5.1

Multilingual
TGN is multilingual. This means that the names may be flagged and hierarchies may be constructed in multiple languages. However, the notes and other fields in the record are generally in American English.

2.1.5.2

Alphabet
Names, descriptive notes, and other fields are expressed using Unicode. If terms or scope notes are contributed in an alphabet or writing system other than the Roman alphabet, an English-use translation in the Roman alphabet must also be included (although the name itself is not necessarily comprising English words).

2.1.5.3

Diacritics
The TGN is published in Unicode. However, in legacy TGN data special codes may used to represent diacritics (e.g., M$04unchen contains the umlaut code for München).

• The legacy diacritical codes are 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
    [name with an umlaut in display]
  • München (preferred, C,V,N) ............meaning "Home of the Monks," name used in some form since 12th century
    Munich (C,O,N,English-Preferred)
    Monaco (C,O,N)
    Monaco di Baviera (C,O,N)
    Munichen (H,O,N)
    

2.1.6

Production goals

• Editors are assigned quotas for the number of records that they should complete each day. The quota differs depending upon the editorial task. Your supervisor will provide you with the target quota for the task assigned to you.
  
  
• Typically, the quotas are gathered at the end of each month and the number of records per day is averaged over the days worked during that month. Your supervisor may tally your quota for smaller periods of time as warranted. In order to meet your quota, it is recommended that you meet your quota each day rather than trying to make it up at the end of the month.

2.1.7

Leaving unfinished records overnight

• Do not leave unfinished records overnight. This is particularly critical on nights when data extractions will be made for the various data releases. At the end of each day, all records in the regular, publishable sections of the hierarchy must be ready for publication.

2.1.8

Quality control

• Avoid typographical errors at all costs. Proofread your work carefully.
  
  
• If you have a problem with typos, for notes and other texts, it is recommended to copy the note into Word, run spell check, and then paste the corrected note into VCS (but do not paste any special characters from Word).
  
  
• Pay special attention to names, because they are the most important part of the TGN record, yet the most difficult in which to spot errors.

2.1.9

Avoid plagiarism

2.1.9.1

Published sources
Caveat: Do not copy texts from published sources verbatim! Read, analyze, and rephrase the material. Do not jump to conclusions or state more than is confirmed in your sources.

• It is permitted to copy texts from the Web provided you do so only as a reference. You must rewrite any such text and cite the source.
  
  
• To avoid pasting illegal characters into VCS, first put the Web text into Notepad, and then copy it from Notepad before pasting it into VCS.
  
  
• It is required to cite the published source of names and the information in notes. Include the page number or other appropriate reference to the passage where you found the name or other information.
  
  
• Sources may be linked directly to each Name and to the Descriptive Note. For other information, note the source in the overall Subject citation designation.

2.1.9.2

Contributors
It is required to include the contributor who provided Names and the Descriptive Note. Generally, the contributor is automatically assigned when the data is loaded and the editor need not worry about it (other than to avoid deleting the contributor or misrepresenting the contribution).

2.1.9.2.1

What is a contributor?
A contributor to VCS is an institution or occasionally an individual person who does one of the following: 1) They use programmers to process data files that originated in their institution and they send us their data in our XML contribution format, or 2) they use our online contribution form to fill in data based on their own local data. In either case, the contributor is handling the data; their data is not being interpreted by the Vocabulary Program. If an institution or person sends us hardcopy information that we in the Vocabulary Program enter into VCS, that institution or person is NOT a contributor per se. They are considered a source for the data, but they are not a contributor because they do not physically provide data in a format that may be entered into our system. Given that there is some interpretation going on when we enter the data by hand, the Vocabulary Program is the contributor in these cases.

• To avoid misrepresenting the contributor's contribution, if you change a Name or significantly change a Descriptive Note that had been provided by a contributor, change the contributor to "VP" (for Vocabulary Program) and make a link through Source to the contributor's database.
  
  
• Caveat: Note that you would change a Name contributed by a contributor only in special circumstances that have been approved by your supervisor. Normally, you should not edit a contributor's contributed place Name. If you need to add a modified version of the name, make a new name with contributor "VP"; do not delete or edit the contributed name unless directed to do so by your supervisor.
  

2.1.10

Uncertainty and ambiguity in display fields

• When important information, such as dates of habitation, is uncertain, the information may still be recorded, but with an indication of uncertainty or approximation in a Descriptive Note or Display Date field (e.g., "ca." or "probably").
  
  
• Never express more certainty than is warranted by your sources. If there is disagreement among reliable sources, use terms such as probably or otherwise express the uncertainty (e.g., "some scholars believe that the site was inhabited in the Paleolithic period"). Consider idiosyncrasies of contributed data (where data may have been parsed incorrectly by algorithm out of various systems) and your published sources; analyze what is true and what is only possibly or probably true.
  
  
• Index important information in the note or display field using appropriate indexing fields and estimating data for retrieval. See the discussion of individual Display Date and Descriptive Note fields below for more information.

2.1.11

Uncertainty and ambiguity in indexing fields

• Indexing fields are intended for retrieval. Any field that contains a controlled number (e.g., Start Date) or values controlled by pick lists (e.g., Vernacular flag) or controlled files (e.g., Language) are indexing fields. Consider retrieval issues when you assign terms and values to such fields.
  
  
• When fields do not display to end users: For fields that do not display to end users, such as the Start Date and End Date, estimate broadly the span of time that is applicable. Estimating too narrowly will result in failed retrieval. Estimating overly broadly will result in false hits in retrieval.
  
  
• When fields display to end users: For fields that display to end users, which are most fields in TGN, do not make wild estimations. However, if a specific value is in question, use a broader value or use both of two possible values, depending upon the circumstances.
  
  
  • Knowable information: For information that is knowable but simply unknown by you, typically you should use a more general term. For example, if you are uncertain if the place is a river port or a seaport because your source is ambiguous, use the more general Place Type port. The more specific information is probably knowable in this case, if you had the time and research materials necessary. But since you do not know it, you should not use a specific term or terms because it will be misleading to the end user.
    
    
  • Debated information: For information that is unknowable because scholars disagree given that the historical or archaeological information is incomplete or interpretation of the information is debated, you may index using multiple terms to allow good retrieval. In such cases, you must explain the ambiguity or uncertainty in a Display Date or Descriptive Note. For example, if scholars disagree regarding whether an archaeological site was a settlement or a ceremonial center where no one dwelled, you should explain this in the Descriptive Note or in the Display Date for one of the Place Types, and index the place using both inhabited place and ceremonial center Place Types (they would be Historical Place Types; see the discussion of Place Types below).
    
    
  • Flags: For flags, where you must choose one value only, make the best choice based on the information at hand. If there is any doubt, consult with your supervisor. For example, sometimes it may be difficult to determine if a name is Current or Historical; but given that this information is knowable, avoid using Unknown when possible. See further discussion of individual fields in the relevant chapters.

2.1.12

Uncertain identification of a place

• In some cases, the identification of a place is a matter of conjecture and dispute. One of the main areas of scholarly dispute in the fields of historical geography and archaeology is the identification of existing sites with their ancient namesakes or counterparts. (For example, is the ancient deserted settlement and archaeological site Yavneh-Yam south of Tel Aviv the same place as the medieval town known as Mahuz Yibna? Scholarly opinion was formerly divided, but now is generally in agreement that the two names refer to the same place.)
  
  
• Rely on general scholarly opinion to decide whether both names should appear in the same TGN record or in separate records (representing separate places). When scholarly opinion is split, make them separate records, and note the possible connection in descriptive note and through an associative relationship. See also Associative Relationships.

2.2

Merging records

• Each record in TGN may contain information from multiple contributors, all of which typically had records for the place in their own databases. Contributors to TGN include various Getty projects and qualified outside institutions. The Vocabulary Program also contributes original information to TGN.
  
  
• If two records are contributed for the same place, they must be merged in VCS. The Vocabulary Program or approved surrogates merge multiple records that represent the same place.
  
  
• In the merged record, the contributors' brief name appears with the Names and Descriptive Note that they have contributed. Other fields in the database 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
Merge two or more records only when the records clearly represent the same place.

2.2.1.1.1

Matching the name, coordinates, and place type
Before merging, it must be ascertained that the two records actually represent the same place. The places to be merged must have the same name, same coordinates, and same place type. Alternatively, these fields should contain approximate or equivalent values according to the following rules:

• Names: To merge, names must be variants or alternate names for the same place (including historical names, names in different languages, and names of various degrees of fullness). Note that there may be separate places with very similar names in close proximity to each other; do NOT merge such records.
  
  
• Coordinates: To merge, coordinates may vary by up to 3 minutes. Methods of measuring coordinates vary from atlas to atlas (or between other sources), so a slight variation is acceptable for a merge. For larger variations, you must firmly establish that one or the other source is in error. If one record has no coordinates, establish by other means (e.g., by checking with the contributor or a map) if these two records represent the same place.
  
  
• Place types: To merge, place types may be equivalents rather than exact matches. For example, if one record identifies the place as a stream and another record identifies it as a river, these are considered equivalent place types for the purpose of merging. The Place Type list of equivalents is available in VCS.
  
  
• Caveat re. merging: If in doubt, do NOT merge the records!
  

2.2.1.1.2

Facets
You cannot merge facets. Currently, the only publishable facets in TGN are World and Extraterrestrial Places. The system will not allow you to merge facets, because it would be such a huge processing job that the system could not handle it.

2.2.1.1.3

Continents and Nations
Do NOT merge continents or nations. The nations have large and complex records that must remain authoritative; in addition, the merging process will ruin the carefully laid out sequence of names and other information in the existing record. Merging a continent would be too large a processing job for the system.

• If a contributor's record for a continent or nation contains new information (highly unlikely), add the information by hand to the existing TGN nation record.
  
  
• Exceptions to this rule are historical nations with sparsely filled-in records. Historical nations and empires with robust records should not be merged. If you wish to merge historical nations, check with your supervisor first.
  

2.2.1.1.4

For administrative entities excluding nations
If the boundaries of the historical state, region, province, etc. are exactly the same as the modern entity, the historical names may be included in the record for the modern place. However, if the boundaries differ, these are considered two different places; do NOT merge the records.

2.2.1.1.5

For inhabited places and physical features
If a place was known by a historical name, and the modern name refers to exactly the same point on planet Earth, both names are considered to represent the same place; you may merge the records.

• Caveat re. sources: Know the idiosyncrasies of your source! Note that published sources sometimes treat adjacent places as if they are the same place (e.g., entries in the Princeton Encyclopedia of Classical Sites may imply that an archaeological site and an adjacent town of the same name are the same place, but this is not necessarily true). Nearby or adjacent places should NOT be merged in TGN; they should be separate records, with an associative relationship.
  

2.2.2

Procedures for merging

• After determining that the records absolutely represent the same place, you may "merge." Go to the hierarchy view; mark DOM and REC. Mark the best, primary record as "DOM" (for dominant) and the record(s) that are to be merged into it as "REC" (for recessive). Merge using the menu.
  
  
• Mark list: Before every merge, it is mandatory editorial practice to look at the Mark List window in order to double-check that you have marked the correct records as DOM and REC.
  
  
• After merging, check the merged record and edit as necessary.
  

2.2.2.1

Unmerging
If, in spite of all precautions, you mistakenly merge the wrong records and you notice this error immediately, you may click "unmerge" from the menu. If some time has passed before you notice the mistake, if you are uncertain how to do this, or have any doubt about the "unmerge," consult with your supervisor before doing anything.

2.3

Moving records

2.3.1

Rules for moving

2.3.1.1

When to move records
You will generally be moving records in order to 1) put candidate records in the publishable parts of the hierarchies or 2) update the subdivisions of a nation.

2.3.2

Procedures for moving

• Determine where in the hierarchy the records belong, based on the rules in Chapter 3.1 Hierarchical Relationships. Go to the hierarchy view; mark DOM and REC. Mark the parent record as "DOM" (for dominant) and the record(s) that are to be moved under it as "REC" (for recessive). Move using the menu.
  
  
• Mark list: Before every move, it is mandatory editorial practice to look at the Mark List window in order to double-check that you have marked the correct records as DOM and REC.
  
  
• 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 may click "undo move" from the menu. If time has passed before you have noticed the mistake or if you have done any other editing, the "undo move" will not work and you will have to rebuild correct the hierarchical structure by hand. If you are uncertain how to do this, or have any doubt about the "undo move," consult with your supervisor before doing anything.

2.4

Sample Records

2.4.1

Sample TGN record

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

2.4.2

Sample TGN 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 a TGN record. It is unlikely that all fields of information will be available or appropriate for all places. However, certain information is considered core, and is required for each minimal TGN 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.
  
  
• Some fields are display-only fields that are controlled by the system. For example, the Subject_ID may not be changed by the editor. 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)
    Sort Order (required-default)
    Historical Flag (required-default)
    Dates for relationship to parents
    Parent string (required-default)
    Hierarchy 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 NAMES
    Term ID (required-default)
    Name (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 Names (required-default)
    Preferred Flag for Language (required-default)
    Language Status (required-default)
    Contributor for Name (required-default)
    Preferred Flag for Contributor (required-default)
    Sources for Names (required)
    Page Number for Term Source (required)
    Preferred Flag for Source (required-default)
    Dates for Names
    Display Name Flag (required-default)
    LC Flag (formerly AACR flag)
    Other Flags
    Assigned To note

3.4 DESCRIPTIVE NOTE
    Descriptive Note
    Sources for the Descriptive Note
    Contributors for the Descriptive Note
    Language of Descriptive Note

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

3.6 PLACE TYPE
    Place Type (required)
    Preferred Flag (required-default)
    Sequence Number (required-default)
    Historical Flag (required-default)
    Dates for Place Type

3.7 COORDINATES
    Coordinates
    Latitude: Degree; Minute; Second; Direction; Decimal Degrees
    Longitude: Degree; Minute; Second; Direction; Decimal Degrees
    Bounding Coordinates
    Least Latitude: Degree; Minute; Second; Direction; Decimal Degrees
    Most Latitude: Degree; Minute; Second; Direction; Decimal Degrees
    Least Longitude: Degree; Minute; Second; Direction; Decimal Degrees
    Most Longitude: Degree; Minute; Second; Direction; Decimal Degrees
    Elevation: Feet; Meters

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 2 January 2023
Document is subject to frequent revisions