Merge pull request #83 from ICPSR/update_geo_coverage_input

Updated Geographic Coverage Area input guidance

Author: shallcro

markdown/icpsr_study_schema.md

@@ -1,6 +1,6 @@
 # ICPSR Metadata Schema
 
-Last updated: January 05, 2026
+Last updated: April 14, 2026
 
 This is the metadata schema used to describe data collections at the Inter-university Consortium for Political and Social Research (ICPSR). These rules and definitions represent ICPSR's metadata practices and are intended to (a) assist ICPSR staff with metadata entry, and (b) help ICPSR users -- including data depositors and researchers accessing data -- understand how to use and interpret our metadata.
 
@@ -990,18 +990,19 @@ The Summary is written in the third person and avoids attempting to address issu
 
 **Controlled Vocabulary:** [ICPSR Geographic Names Thesaurus](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10003).
 
-**Usage Notes:**   
-Each geographic term's full hierarchy must be included; please note:   
+**Usage Notes:** Each geographic term's full hierarchy must be included; please note:   
 
 * For a U.S. city, the state and country are listed alongside (e.g., 'Los Angeles, California, United States').   
 * Non-U.S. geographic subdivisions need not include hierarchical relations, with the specific exceptions of Canadian provinces and the countries within the United Kingdom.  
 * 'Global' may be appropriate for studies where the universe of participants is truly worldwide. Possible examples include online surveys that are not restricted by geography, or studies of organizations, such as NGOs.  
 * County-level information is typically not indicated. If a U.S. county will be included, the state name and 'United States' must be listed as well.  
 
-The [Getty Thesaurus of Geographic Names](http://www.getty.edu/research/tools/vocabularies/tgn/index.html) is referenced when introducing new geographic names.  
+The [Getty Thesaurus of Geographic Names](http://www.getty.edu/research/tools/vocabularies/tgn/index.html) is referenced when introducing new geographic names.    
 
 **ICPSR Input Guidance:** The metadata editor will automatically put this element's values in alphabetical order, regardless of hierarchy.
 
+For United States-based data collections that include some or all U.S. island territories (e.g., American Samoa, Puerto Rico, Northern Mariana Islands, Virgin Islands of the United States, and Guam), list each of these territories separately in the Geographic Coverage Areas field.
+
 **Examples:** 
 
 ```json

markdown/version_history.md

@@ -2,6 +2,7 @@
 
 | Date | Version | Note |
 |------|---------|------|
+| April 14, 2026 | v1.3 | Updated ICPSR input guidance for Geographic Coverage Area. |
 | April 11, 2025 | v1.2 | Updated field definitions to improve clarity. |
 | June 28, 2024 | v1.1 | Removed guidance regarding null entries for National Institute of Justice studies. Several fields previously required "None" when otherwise a field would be left blank. Updated internal guidance for 'external source id' and 'funding purpose' elements. Added 'study number' and distributor 'order' elements to address earlier oversights. |
 | Oct. 30, 2023 | v1 | Initial release and publication of the ICPSR Metadata Schema. |

schema/icpsr_study_schema.json

@@ -378,7 +378,6 @@
       "minItems": 1,
       "controlledVocab": "[ICPSR Geographic Names Thesaurus](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10003).",
       "$ref": "https://schemas.icpsr.umich.edu/schema/yaml/geographic_coverage_area?version=v1",
-      "icpsrGuidance": "The metadata editor will automatically put this element's values in alphabetical order, regardless of hierarchy.",
       "examples": [
         ["United States", "Maryland", "Baltimore"],
         ["United Kingdom", "China"],

schema/yaml/geographic_coverage_area.yaml

@@ -2,12 +2,15 @@
   $schema: https://json-schema.org/draft-07/schema#
   $id: https://schemas.icpsr.umich.edu/schema/yaml/geographic_coverage_area?version=v1
   usageNotes: |
-    
     Each geographic term's full hierarchy must be included; please note: 
     
     * For a U.S. city, the state and country are listed alongside (e.g., 'Los Angeles, California, United States'). 
     * Non-U.S. geographic subdivisions need not include hierarchical relations, with the specific exceptions of Canadian provinces and the countries within the United Kingdom.
     * 'Global' may be appropriate for studies where the universe of participants is truly worldwide. Possible examples include online surveys that are not restricted by geography, or studies of organizations, such as NGOs.
     * County-level information is typically not indicated. If a U.S. county will be included, the state name and 'United States' must be listed as well.
 
-    The [Getty Thesaurus of Geographic Names](http://www.getty.edu/research/tools/vocabularies/tgn/index.html) is referenced when introducing new geographic names.  
+    The [Getty Thesaurus of Geographic Names](http://www.getty.edu/research/tools/vocabularies/tgn/index.html) is referenced when introducing new geographic names.  
+  icpsrGuidance: |
+    The metadata editor will automatically put this element's values in alphabetical order, regardless of hierarchy.
+
+    For United States-based data collections that include some or all U.S. island territories (e.g., American Samoa, Puerto Rico, Northern Mariana Islands, Virgin Islands of the United States, and Guam), list each of these territories separately in the Geographic Coverage Areas field.