GIS Index Map Creation

OpenIndexMaps Requirements and Recommendations

Version 1: April 2021

Table of Contents

Overview

Institutions have been creating GIS index maps for many years to inventory and provide a finding aid for map sets and air photo flights. Institutions use various conventions for vector creation, attribute table element names (column headers; fields), attribute data and file names. As a result, one institution’s index maps can look very different from another’s and it may be difficult to interpret local conventions.

From 2017 to 2021 during the annual Geo4Lib Camps at Stanford University, attendees discussed various aspects of GIS index maps. In 2019 the group expressed a desire to standardize vector and attribute table characteristics among multiple institutions so that the files can be easily shared and reused. At the 2019 Geo4Lib Camp and over the next two years, several individuals developed a document outlining requirements and recommendations for GIS index map creation. Drafts were reviewed at the 2020 and 2021 Geo4Lib Camps, and version 1 was finalilzed in April 2021, becoming the original version of this document.

OpenIndexMaps and GeoBlacklight

Also desired by the Geo4Lib Camp attendees was a central place to share GIS index map files, especially those that conform to the proposed specification and best practices. The Open Index Maps GitHub repository (OpenIndexMaps) was set up for this purpose. Each contributing institution can set up a folder within which they can upload their GIS Index Maps. This is also a location to store and share index map documentation.

For further consideration, functionality within the GeoBlacklight discovery platform allows users to click on a polygon within a GIS index map which then forwards users to metadata and links to access the specific item indicated by that polygon. If institutions use common practices to create GIS index maps, and if GeoBlacklight could then be programmed to recognize a file with this specification, then these GIS index maps can easily be added to any institution’s GeoBlacklight-based repository, thus providing direct access to their and other institutions’ scanned maps or air photos without the need for extensive file, code or workflow changes.

The goal is for institutions to use the recommendations in this document to create GIS index maps (or adjust current GIS index maps to match this specification) and then upload the files to the OpenIndexMaps repository. Additionally, institutions could ingest the GIS index maps into their GeoBlacklight instances, which could then use its functionality to provide information and improve access to map sets and air photo collections. Institutions could also ingest other institutions’ GIS index maps, expanding access to collections.

Requirements and Recommendations

The following requirements and recommendations for creating GIS index maps and entering information are designed to enforce conformity where necessary for sharing and reuse while allowing for flexibility at each institution to implement local practices.

1. File coverage

Recommendation: one file per institution; one file per map set or air photo flight

Each file should represent a single map set or air photo flight held at a specific institution so that discovery tools such as GeoBlacklight can display each institution’s holdings of that work as a single record.

2. File naming convention

No recommendation is made at this time regarding file names. At this time, GeoBlacklight has no requirements or recommendations for file names.

3. File formats

Requirement: GeoJSON

While it is recognized that GIS index maps may be created using a variety of file formats (shapefiles, geodatabase feature classes, etc.), the ultimate file format shared with the community and uploaded to GeoBlacklight SHOULD be valid GeoJSON. The preference here is for open standards based, self-contained and human-readable text files; GeoJSON satisfies these preferences. See RFC 7946 for more on GeoJSON.

4. Projections and coordinate systems

Requirement: WGS84 (EPSG: 4326)

Valid GeoJSON requires the coordinate reference system to be WGS84. See “Coordinate Reference System”. However, OpenIndexMaps will adhere to the exception “However, where all involved parties have a prior arrangement, alternative coordinate reference systems can be used without risk of data being misinterpreted” in special cases.

5. Element name character length

Recommendation: 10 or less for recommended and required elements (see ‘Element name’); use latin alphanumeric characters only; do not start with a number. No limit in length or character type for all other element names

Many GIS index maps are in shapefile format, or at some point have been or will be a shapefile, which has a 10-character element name (attribute name; column header) limit. To reduce error or the need for maintenance due to element name truncation when creating or converting to shapefiles, element names should be 10 or less characters. However, as this is not always an issue, only those elements covered by these requirements and recommendations should conform to this rule. Any additional elements created locally need not comply with this recommendation.

6. Element name format

Recommendation (Requirement for GeoBlacklight): camelCase; Latin alphanumeric characters only

As GeoBlacklight and other software can be programmed to recognize element names, adherence to a standard is imperative. Also, with a limitation of 10 characters for element names (see ‘Element name character length’), camelCase maximizes character use while retaining legibility.

It is recommended to only use Latin alphanumeric characters in those elements specified by this document (required for GeoBlacklight). This recommendation (requirement) does not apply to other elements devised by an institution.

7. Element name

Recommendation (Requirement for GeoBlacklight): the term as specified in the tables in the next section

Interoperability is possible when the element name is recorded identically in both the attribute table and programming code. For those GIS index maps destined for GeoBlacklight, the element names in the attribute table shall be consistent with the element names listed below.

Element names beyond those listed in the tables below are at the discretion of each institution.

8. Map extent geometry - vector creation

Recommendation: one polygon for each map extent within the map set (or one polygon for each air photo extent within the flight). When there are multiple versions or editions of a map sheet that have the same map extent, create one polygon per version or edition.

Inventory and discovery of map sets and air photo flights are clearer when each polygon represents only a single edition or version of a map sheet or air photo. Interfaces such as GeoBlacklight should be programmed to allow for overlapping polygons such that selection of a point or area within the overlapping polygons results in a display of metadata for all overlapping polygons.

For inset maps or complex map extents, no recommendation is made regarding vector creation. The extent could be a single polygon or multi-part polygon covering the main map and inset map extents. The selection of overlapping and multi-part polygons is already supported by Leaflet; however, GeoBlacklight would need to be updated to support this.

No recommendation is made regarding the creation of polygons in locations where no item should exist (such as a topo map over open water) or might not exist (such as where the extent of a map set is unknown). As no information will be linked to these polygons, inventory and discovery are not compromised by their presence. (See ‘Holdings information - general’)

9. Bounding box - data entry

Recommendation: use decimal degrees to enter extents.

If recording a rectangular bounding box for a sheet map, the westernmost and easternmost longitude and the northernmost and southernmost latitude forming the extent of a map sheet or air photo frame should be recorded in separate elements using decimal degrees. (See the list of element names in the next section for the four elements.) These units are recognized by map interfaces using WGS84 (see ‘Projections and coordinate systems’). Record longitude using the Greenwich Meridian.

Any bounding box that crosses the antimeridian SHOULD be represented by cutting it in two such that neither part’s representation crosses the antimeridian. See RFC 7946 Section 3.1.9.

10. Holdings information - general

Recommendation (Requirement for GeoBlacklight): “true” (lower case, without quotes, native Boolean value) entered in the attribute table under the element called ‘available’ to indicate that the institution holds at least one copy of the map sheet or air photo frame in any format (paper, digital, negative, etc.)

Recommendation (Requirement for GeoBlacklight): “false” (lower case, without quotes, native Boolean value) entered in the attribute table under the element called ‘available’ to indicate that the institution does not hold any copy of the map sheet or air photo frame in any format (paper, digital, negative, etc.)

Interfaces such as GeoBlacklight can read the values of this element and color code GIS index map polygons accordingly to indicate an institution’s holdings. Further distinction of holdings can be expressed in the physHold and digHold elements (see ‘Physical holdings information’ and ‘Digital holdings information’).

11. Physical holdings information

Recommendation: enter a string in the attribute table under the ‘physHold’ element to indicate that the institution holds a physical version of that item

Requirement for GeoBlacklight: enter a URL or a text string under the ‘physHold’ element that provides direct access or access information for the sheet map or air photo frame

Each institution can choose how they wish to use this element. If using GeoBlacklight, a URL or text string entered in the field will appear as a link or text on the popup when the polygon is selected by a user.

12. Digital holdings information

Recommendation: enter a string in the attribute table under the ‘digHold’ element to indicate that the institution holds a digital version of that item

Requirement for GeoBlacklight: enter a URL or a text string under the ‘digHold’ element that provides direct access or access information for the sheet map or air photo frame

Each institution can choose how they wish to use this element. If using GeoBlacklight, a URL or text string entered in the field will appear as a link or text on the popup when the polygon is selected by a user.

13. Sheet or frame number

Recommendation: whenever possible, enter the sheet or frame number exactly as it is displayed on the item

Whenever possible, the sheet number (or code) or frame number should be recorded in the same way as it is displayed on the item. For example, if a map sheet has a code “M-16”, the M should be capitalized and the dash should be included. This is recommended primarily to facilitate joining tables on this element and for other institutions to confirm that they have the same item.

14. Dates

Recommendation: enter dates using the Extended Date/Time Format (EDTF) Specification

Recommendation: For date-specific elements, the element field type should be ‘string’

Dates should be entered using the EDTF format (e.g. YYYY, YYYY-MM-DD) so that discovery interfaces may recognize it as such. The EDTF format provides for qualification of dates (approximations, date ranges, etc.). Follow EDTF recommendations for these cases.

Elements should not use the ‘date’ field type, as there is inconsistency in the way different systems export their internal date formats to JSON values.

15. Websites

Recommendation: use HTTPS and serve with CORS enabled

Whenever possible, URLs should use HTTPS and websites should serve with CORS (Cross-origin resource sharing) enabled.

Element Names

The following element names are recommended for use in GIS index map attribute tables. All elements are optional. Element names beyond those listed in the tables below are at the discretion of each institution. Empty elements should be omitted.

TABLE 1: Elements pertaining to both map sheets and air photo frames

ELEMENT USED FOR TYPE DESCRIPTION EXAMPLE
label Sheet/frame no. string Alphanumeric code identifying the sheet or frame. The value of this field is used as a tool tip in GeoBlacklight. L-16
labelAlt Alternate sheet/frame no. string Alphanumeric code for the sheet or frame that was used for previous or subsequent editions, or for when there are multiple labels NW8
labelAlt2 Second alternate sheet/frame no. string Alphanumeric code for the sheet or frame when there are multiple labels C17
datePub Publication date string The date that the sheet or frame was published or made available 1978-08
date Date string Used when no other date field is relevant 1978
west Westernmost longitude number Farthest west extent of the sheet/frame bounding box (using the Greenwich Meridian) -112.32645
east Easternmost longitude number Farthest east extent of the sheet/frame bounding box (using the Greenwich Meridian) -108.32555
north Northernmost latitude number Farthest north extent of the sheet/frame bounding box 38.7221
south Southernmost latitude number Farthest south extent of the sheet/frame bounding box 30.4656
location Location array[String]* Geographic place name identifying the area covered by the map sheet or air photo frame [“Fresno”, “Clovis”]
scale Scale string Scale statement (representative fraction plus qualifiers) of the individual sheet/frame approximately 1:250,000
color Color, b&w, infrared string Indicates whether the sheet/frame is color, black and white, color infrared or another color type Color, Black and white

* See Converting geospatial data to OpenIndexMap GeoJSON format section below.

TABLE 2: Elements pertaining to map sheets only

ELEMENT USED FOR TYPE DESCRIPTION EXAMPLE
title Sheet name string Title of map, usually a geographic location on that sheet Santiago
titleAlt Alternate sheet name string Alternate title for the sheet that was used for previous or subsequent editions, or for when there are multiple titles Rio Branco
dateSurvey Survey date string Date that the map sheet was surveyed 1957
datePhoto Photocorrected date string Date that the map sheet was photocorrected 1966
dateReprnt Reprint date string Date that the map sheet was reprinted 1972
overprint Overprint string    
edition Edition string Statement indicating the edition of the map sheet 3rd edition
publisher Publisher string Publisher of the individual sheet (can be used if publishers vary within a map set) Conselho Nacional de Geografia
overlays Overlays string    
projection Projection string The map’s or photo’s projection, coordinate system and datum  
lcCallNo LC Call Number string Library of Congress call number  
contLines Contour lines boolean Indication of whether or not there are contour lines on the map true / false
contInterv Contour interval string Distance between contour lines. Include unit (or abbreviation). 200 m
bathLines Bathymetric lines boolean Indication of whether or not there are bathymetric contour lines on the map true / false
bathInterv Bathymetric interval string Distance between bathymetric contour lines. Include unit (or abbreviation) 200 m
primeMer Prime Meridian string Indicates a prime meridian other than Greenwich Ferro

TABLE 3: Elements pertaining to air photo frames only

ELEMENT USED FOR TYPE DESCRIPTION EXAMPLE
photomos Photomosaic Boolean Indication that the image is a mosaic of several air photos true / false
bands Bands string Spectral bands present (near infrared, red, green, blue, etc.)  
rectificn Rectification string Any corrections done to adjust the air photo image orthorectified
rollNo Roll number string Identifier for the film reel from which the air photo comes  

TABLE 4: Elements for entering metadata pertaining to a specific institution only

ELEMENT USED FOR TYPE DESCRIPTION EXAMPLE
inst Institution string Local institution holding material  
sheetId Sheet ID string Local institutions’s unique identifier for the sheet/frame G103 U51 1970 S-34
available Available boolean Indication if the institution holds the item at this location in any format true / false
physHold Physical holdings string Indication if the institution holds the item in a physical format, or a link to information about the physical object  
digHold Digital holdings string Indication if the institution holds the item in a digital format, or a link to information about the digital object, or a link to the digital object itself  
instCallNo Local call number string Call number used locally (other than Library of Congress call number) 3200s 250 u5
recId Record identifier string Local institution’s unique identifier for the digital object yr314gw9982
download Download URL string Link used to directly download the digital object  
websiteUrl Website URL string Link used to direct users to a website with metadata or a download link for the digital object  
thumbUrl Thumbnail URL string Link used to access the thumbnail for the digital object  
iiifUrl IIIF URL string Link used to access the digital image using IIIF  
fileName File name string Digital file associated with sheet/frame 6840s_100_r8_e-49-63.tif
note Notes string Free text for local comments as well as general notes applying to everyone’s copy  

Set- and Flight-level Metadata

While metadata pertaining to individual map sheets or air photo frames are recorded in GIS index map attribute tables, metadata pertaining to the map set or flight as a whole are not documented in a consistent location. Esri shapefiles and geodatabase feature classes can have Esri-formatted metadata attached to the files. However, this information is lost when the files are converted to GeoJSON. One option is to add elements to the attribute table and enter the information in each row of the table.

For version 1 of this document, no recommendation is made regarding the identification of set- and flight-level metadata. However, this is an imporatant topic that will be addressed in a subsequent version.

Converting geospatial data to OpenIndexMap GeoJSON format

Boolean conventions for conversion

While there currently is no tool to convert true and false text strings into Boolean elements within a GIS index map attribute table when converting to the OpenIndexMap GeoJSON format, it is the goal of this group to create one in the future.

Array conventions for conversion

The pipe | should be used as a delimiter (for example, Fresno|Clovis) when entering string data that should be converted to an array during conversion to the OpenIndexMap GeoJSON format.

Uploading to OpenIndexMaps

Institutions can contribute to OpenIndexMaps by uploading their own index maps here: https://github.com/OpenIndexMaps

To upload your index maps to OpenIndexMaps, please submit an Issue to have a repository created for your institution. In your Issue description, provide the GitHub user account which will be the primary user of your repository, and the URL for your institution. Once created, you can add your files using Git, GitHub Desktop, or by dragging and dropping files from your computer to your repository using your web browser.

Files uploaded to your institution’s repository should be stored in folders named to reflect the specification version used to create them. For example, use 1 or v1 to indicate version 1 of this document.

Participants

The following individuals contributed to the development of these requirements and recommendations:

  • Stephen Appel (University of Wisconsin Milwaukee)
  • Tom Brittnacher (University of California Santa Barbara)
  • Kim Durante (Stanford University)
  • Dave Hendlin (University of California Santa Barbara)
  • Taylor Hixson (New York University, Abu Dhabi)
  • Keith Jenkins (Cornell University)
  • Stace Maples (Stanford University)
  • David Medeiros (Stanford University)
  • Susan Powell (University of California Berkeley)
  • Jack Reed (Stanford University)
  • Evan Thornberry (University of British Columbia)
  • Phil White (University of Colorado Boulder)
  • Amy Work (University of California San Diego)