The Getty
Research Home Search Tools & Databases Learn about the Getty Vocabularies Editorial Guidelines Getty Thesaurus of Geographic Names Online
Art & Architecture Thesaurus Online
3. Editorial Rules, continued






Administrative Flags, Notes, and Revision History

Included in this chapter





Comment Flag




Flag indicating if a critical comment is applicable to the record, including if the record represents a special case among similar or homographic terms, or if a contributed record is an additon or revision to an existing record, as distinguished from a new record.




Values are controlled by a list.

    Famous / Noted
    Comment Candidate Record
    Not a Comment Candidate
    Not Applicable




This field is used for contributions, to flag records that are comments on existing records (thus requiring merging) as distinct from new records.

An important function of this field in TGN is to flag records for places that may be assumed to be intended in texts or databases when only the place name is referenced without additional information, including the nation to which the place belongs. Examples of place names used without broader context or other information are in reference to places of publication and current or former locations of architecture or art.

Implementors seeking automated matches between such texts or data and TGN names may assume that, when multiple matches for the name are found in the TGN, the TGN record flagged famous/noted is intended if no other information is given. Examples are Florence and Cairo, which, in the absence of other information in texts or other sources, almost always refer to Florence, the city in Italy, and Cairo, the city in Egypt.

If a record is flagged famous/noted, it should assume priority only in matches using the record-preferred name, a preferred name in another language (e.g., French = Preferred). In some cases, the comparison will be successful if made on the site name (Other Flag = Site), although this comparison is not always reliable. Do not make the comparison for famous/noted using other names in the compared records.



RULES for Comment Flag



Minimum Requirements

Required-default: This flag for Comment or Not a Comment is typically set in the data load. Editors generally should not change the flag, other than to flag Famous / Noted.



How to apply the Comment Flag

    Apply the comment flag as necessary using the definitions below.

  • Famous / Noted: For Records having terms or names that are homographs with other works, and for which the identification may be confused, if one of the records is extremely well known and often referred to by name alone, flag it as Famous / Noted. In the TGN, generally reserve this flag for places that are famous and commonly referenced as places of publication or are the largest or most important of those having homographic names.

    The purpose of this flag is to distinguish the well known place from others having the same or similar term or name for the purposes of matching and in retrieval.

    Caveat: Be very circumspect when applying the Famous/Noted flag. It should be used only in the rare cases where the name is typically used in texts and databases without additional information and always intended to refer the same place.

  • Comment Candidate Record: For new contributions, indicates records that were submitted as "comments" on existing records; that is, they are requests for additions to or changes to an existing vocabulary record. When this flag is set to "C," the record typically should be merged with an existing record.

  • Not a Comment Candidate: For new contributions, indicates that the record is a new record to be included with a new subject_id in TGN, not as a comment on an existing record.

  • Not Applicable: Default value indicating that the Comment Flag is not applicable for this record.





Problem flag



Flag indicating if there is a problem requiring editorial attention.



Controlled by a list.




RULES for Problem Flag



Minimum Requirements

Optional: Use Problem Flag as necessary.



When to use Problem Flag

  • For Place Records
    This flag is most often used to flag a record placed under a temp.parent that is not yet published. Such records should be omitted in the Candidate Report for contributors.

    Do not flag Problem Flag = Yes for records that are in the published hierarchies.

  • For temp.parent levels
    Additionally, for temp.parent records themselves that are created for as a level for testing, deleted records, or otherwise should not be visible to contributors, set the Problem flag to Yes.

    Do not publish children of Problems
    In reports and other methods of revealing candidates to contributors or other users, do not include the record having Problem = Yes nor any children of that record.

  • Describe the problem
    If the problem flag is set the flag to Yes, describe the problem in the Editor Note, including your initials and the date.

    • [Blank]: No value. Currently many records in TGN are set to Blank. When records are loaded, they are not automatically set with Problem = No.

    • Yes: Indicates there is a problem with the record.

    • No: Indicates that there perhaps was an earlier problem, but it has been resolved.





Assigned To



Note indicating to which editor the record was assigned.



Free text. Unicode characters and numbers.



RULES for Assigned To



Minimum Requirements

Optional: Use this field as necessary.

  • The supervisor or her delegate will fill in this field. Values should be the initials or user name of an editor (e.g., PHarpring).

  • If your name appears in this field, you are responsible for editing the record and all children under it.





Special Project


Indication of a special project for which the record is a part, including projects having to do with a given theme or discipline.



Values are controlled by an extensible list. The list comprises a code and description.

  • Examples
  • Arc - Archaeology: Records added for the discipline of archaeology
  • Con - Conservation: Records added for the discipline of conservation
  • SAH - Society of Architectural Historians
  • VRA - Visual Resources Association


This flag may be used during the editorial processing of the record and also in the retrieval of the record.

For retrieval, this flag may be used to gather a significant set of records having to do with a particular project, theme, or discipline.

An example of usage of this flag could include a project by the archaeology community to submit records for names representing sites needed for that community. Although such a flag could not be assumed to capture all TGN records relevant to archaeology, it may provide a useful set of records that have been so far considered and approved by that community.

Another example of usage could include a project initiated by the Visual Resources Association to contribute new records for place names needed by their community.

How is this field related to the Contributors fields linked to Terms/Names, Scope/Descriptive Notes, and the overall record? Each contributor represents the institution that made the contribution, but Special Project identifies the project of which this effort was a part.


RULES for Special Project


Minimum Requirements

Optional: Designate special projects as necessary.


How to designate a Special Project

  • Use codes that have been authorized by your supervisor and available in the list.

  • If the record has been designated as a subset for a particular special project (e.g., VRA), the code will have been loaded with a contribution. Alternatively, the code may be entered by hand by a Vocbulary Program editor.




Sequence Number for Special Project


The Display Order number (or Sort Order number), indicating priority, order of contribution, or alphabetical order.


Values begin with 1 and are numbered sequentially; there is no upper limit imposed by the system


RULES for Sequence Number


Minimum Requirements

Required-default: If there is a special project, Sequence Number is required. If there is only one special project, the default value is 1. If there are multiple images, sort them in an appropriate sequence by priority, by order of contribution, or alphabetically.





Facet Code



Facet code is used to indicate the facet to which the record belongs. This is a legacy indicator, currently retained only in the AAT.


Unicode characters and numbers.


This field is system-generated. In TGN, it currently contains the subject_id of the top of the TGN hierarchies, 1000000.






Legacy ID


Numeric or alphanumeric identification that was used for this record in previous systems.



The purpose of this field is to provide implementers with a means to map older TGN data having old IDs with new releases.

In TGN, it is anticipated that the currently assigned IDs will be persistent.

IDs for contributors records
Note that in the TGN data, the contributors original, internal or local ID for a record is retained for comparison and reference for the additon of new contributions in future. That field is separate from the currently-discussed Legacy ID field, and is invisible to VCS editors.


RULES for Legacy ID


Minimum Requirements

Optional: The field is system-generated. Editors cannot change it.





Class Notation


Brief justification or explanation of the classification or hierarchical placement of the record.


Free text. Use Unicode characters and numbers


In some cases, it is useful for users to know why a certain classification or hierarchical position was chosen. If the choice is does not require explanation, do not use this field.

In the AAT, the analogous Class Notation field formerly had a different function. The field may be seen in legacy AAT records as a string that was formerly used to build hierarchies in the 1980s.


RULES for Class Notation


Minimum Requirements

If necessary, enter brief justification of classification or hierarchical placement of the record, or for broader contexts, for the children of the record. It may repeat information in the Public Note of Revision History, if pertinent.





Media / Image


Link to a persistent URL that illustrates the work


Includes only persistent URLs that illustrate the place or that are maps. Formerly, image files also were collected in VCS, but the overhead for storing images and ascertaining copyright permissions has been deemed impractical.


RULES for Media / Image


Minimum Requirement

Optional: It is optional but highly recommended to include links to maps of the places, as time and editorial priorities allow. Contributors should include a link to map, if one is available.


How to link to an image

  • Persistent URL
    Link only to persistent URLs for the map or other image.

  • Sources for images
    Sources for images should be the following:

    • Official mapping sites.

    • Museum or other repository sites.

    • Images in Open Content or in the Public Domain having a persistent URL.

    • Avoid dot-com sites; however reliable online dot-com data bases may be used. Check with the Vocabulary Program before linking to a dot-com site.

  • How to choose an image

    Choose images that are of good quality and are maps or photographs, prints, or other images that represent the place well.

    The first priority should be to include an image that best represents the overall place or a map.

    Additional images may include details or historical depictions of the place.





Sequence Number for Image


The Display Order number (or Sort Order number), indicating the sequence of the images in displays.


Values begin with 1 and are numbered sequentially; there is no upper limit imposed by the system.


RULES for Sequence Number


Minimum Requirements

Required-default: If there is an image, Sequence Number is required. If there is only one image, the default value is 1. If there are multiple images, sort them in an appropriate sequence.






Index Note


Information about the data load or sources of the data.


Free text field. Use Unicode characters or numbers.


RULES for Index Note


Minimum Requirements

Optional: It is optional to include the index note.


How to record Index Note

  • For data loads, the system administrator should include the date, contributor, and other information relevant to a major data load.

  • Given that this note is not repeatable, separate individual comments with semi-colons. For each comment, include the contributor Brief Name to identify to which contribution the comment applies.

    • Example
    • Index Note: 2010-06-22, VP: Unique Feature ID: -117543; Region Code: 1; Country Code 1: IT; Subdivision Code 1: 16; Military Grid Reference System: 32TPP8109948418; Joint Operations Graphic Reference: NK32-03; Feature Classification: P; Modify Date: 2004-10-21




Not Found Note


Note listing sources that were consulted but that did not contain information about the work.


Free text field. Use Unicode characters or numbers.


RULES for Not Found Note


Minimum Requirements

Optional: It is optional to include the not found note.


How to record Not Found Note

  • Which sources to include
    Record well known sources in which information could be expected to be found on the place, however the place is not included. Do not include minor sources or journal articles that fail to mention the place.

  • Who records the Not Found Note
    Various contributors record this information; it is loaded into this field.

    Vocabulary Program editors may also enter values in this field.

  • Content of the Note
    Given that this note is not repeatable, separate individual sources with semi-colons. For each source, comments may also be included.

    Include a reference to the contributor (the Brief Name for the contributor) of information before each source or set of sources.

  • Use the VCS Sources file Brief Citation to refer to the source.

    • Example
    • Not Found Note: BHA: Library of Congress Authorities online (2002-); NGA, GEOnet Names Server (2008-); Princeton Encyclopedia of Classical Sites [online];




Status Note


Note elaborating upon special circumstances regarding the status of the records.


Free text field. Use Unicode characters or numbers.


RULES for Status Note


Minimum Requirements

Optional: It is optional to include the status note.


How to record Status Note

  • The Status Note is often a note explaining the Review Status of the record.

  • For data loads, the system administrator could include a note relevant to the status of the record.

  • Vocabulary Program editors may note a particular status of a record or for a broader context for multiple records.

  • Given that this note is not repeatable, separate individual comments with semi-colons. For each comment, include the contributor Brief Name or editor name to identify to which status comment applies. Include the date when the status was analyzed.

    • Example
    • Status Note: PH: 2012-13-11, holding status, children of this parent seem to be duplicates for children of 7003163 Firenze province;




Editor Note


Note for editorial problems or decisions associated with the record.


Free text field. Use Unicode characters or numbers.


RULES for Editor Note


Minimum Requirements

Optional: It is optional to include the editor note.


How to record Editor Note

  • Record information about issues, problems, or other information important for the ongoing editorial work editorial history of the record.

    Include reasons for editorial decisions where questions could arise.

  • This note will not be visible to end-users.

  • Explain circumstances regarding designations of Problem Flag.

  • Include your initials and the date of your comment.

    • Example
    • Editor Note: PH January 2013, choice of preferred vernacular spelling based on slightly higher counts of usage in authorized sources;




Revision History fields (required-default)


Audit trail of editorial work on the record, including action, editor, and date.



Use Unicode characters or numbers. Certain flags are controlled, while others are note fields.


The Revision History is, for the most part, system-generated. Each individual field is not treated as a separate section in this manual. Instead, brief explanations of what the fields mean are included here.


Rules for Revision History


Minimum Requirements

Required-default: System-generated values should not be edited or deleted, except for certain note fields, as described below.


How to interpret and edit Revision History

  • Interpret the fields in the Revision History according to the definitions below.

  • Editors should add or edit information in the Public Note and Private Note as indicated below.

  • The fields in each row are linked, repeatable as a row.


Revision History Type

  • Type: Refers to the part of the record that was affected by the Action. Types include the following values:

      S = Subject: Refers to changes or additions made to the record as a whole or to any field other than Term/Name, Associative Relationships, or Note, which have separate Type flags.

      T = Term/Name: Refers to changes made to a term, title, or name in the record. The value of the term, name, or title added or changed, and an indication if it is a new term is noted in the associated Public Note.

      A = Associative relationships: Refers to new Associative Relationships added to the record. An identification of the linked subject record and the relationship type are listed in the linked Public Note.

      N = Note: Refers to additions or changes made to the Scope Note/Descriptive Note. The language of the note is listed in Public Note.


Revision History Action

  • Action: Refers to the Action taken by the editor or system administrator, including the following values and definitions:

      created: Used with Type = Subject or Note, incating when and by whom (usually the Loader or a Vocabulary Program Editor) a record was created or a Scope Note/Descriptive note was created.

      updated: Used with Type = Subject, Term, Note, or Associative Relationship, indicating a change has been made to that entity.

      moved: Used with Type = Subject, indicates when a record is moved from one parent to another. Old Parent is listed in the Public Note.

      merged: Used with Type = Subject, indicates when two records are merged. The identification of the records are listed in the Public Note.

      parent added: Used with Type = Subject, indicating when a subject record had the addition of a non-preferred parent.

      added: Used with Type = Term, Note, or Associative Relationship, indicating the type of entity has been added to the record.

      deleted: Used with Type = Term, Associative Relationship, or Note, noting when an element was deleted from the record. The identity of the deleted entity is recorded in the Public Note.

      published: Used with Type = Subject, indicating the record was published in the annual publication release, on a certain date. The publication as APIs, LOD, and in the online search mechanism every two weeks is not noted by this flag; as of this writing, it refers to only the annual publications.

      noncandidate: Used with Type = Subject, indicating the record was moved from candidate status to non-candidate status, meaning it is processed and available for publication.


Revision History User Name

  • User Name: An indication of the editor or system activity that is responsible for the action. As of this writing, values include the following:

      Editor login: Login name of the editor (e.g., JWARD).

      SYSADM: Refers to the system administrator, meaning an action was done globally by programming instead of editing manually.

      LOADER: Refers to the automated loading of records, done through programming rather than manually. LOADER-<NAME> (e.g., LOADER-GRL), includes the brief name of the contributor from whom the loader data was acquired.


Revision History Date Time

  • Date Time: Refers to the time and date when an action occurred.

    Format: The time stamp is expressed by month, day, year, hour, minute, and second in the following format: MM/DD/YYYY HH:MM:SS. It is expressed according to the time zone in which the action was taken, Pacific Standard Time (PST).


Revision History Public Note

  • Public Note: Note containing specific information or comments regarding the action indicated in the row. The Public Note is published.

  • Added by the system
    Most comments are, added by the VCS system as editorial work is done. In rare situations, the editor may alter the Public Note.

    If multiple comments are applicable to one row, the comments are separated by semi-colons.

      For Subject
      Notes details about when a subject was created, moved, acquired a non-preferred parent, etc.

      • Example
      • Public Note: Dominant: Firenze (7000457) Recessive: Firenze (7046223)

      For Term/Name/Title
      The Public Note is used when an action was done to a Term/Name, this field describes which term (value and term_id) was Added or Updated.

      • Example
      • Public Note: Fiorenza (165290);

      For Associative Relationship
      The Public Note is used to indicate the linked records and the relationship type between them.

      • Example
      • Public Note: Firenze (7000457) 'ally of' Montepulciano (7006345);

      For Scope/Descriptive Note
      The Public Note is used to indicate the language of the note that was created.

      • Example
      • Public Note: English (70051)

  • Added by the editor
    If notable changes are made by the editor, of such significance that translating projects or other major contributors will require changes to their contributed data (which by policy is not edited by the Vocabulary Program), an indication is made to Public Note.

    If the editor makes such a notation, insert it before the automated note content of the pertinent row, preceding the notation with NB (for Nota Bene) as the first word in the Public Note.

    Contributors may do queries on the Revision History periodically to discover changes that should be made to their data.

    • Example
    • Public Note: NB: SN adjusted, record had contained information for two different, although adjacent, places, second place is now in separate record 2124518 Abashai;


Revision History Private Note

  • Private Note: Note for internal editorial use only, containing comments regarding the action indicated in the row. The Private Note is not published.

    • Example
    • Private Note: PH 12/30/2009: Loads for all children of Asia must all be checked for correct diacritics;



[1] In this chapter, "required-default" indicates that a default is automatically set by the system.


Last updated 19 January 2016
Document is subject to frequent revisions


Back to Top

The J. Paul Getty Trust
The J. Paul Getty Trust
© J. Paul Getty Trust | Privacy Policy | Terms of Use