GIS Index Map Creation
OpenIndexMaps Requirements and Recommendations
Version 1: April 2021
Table of Contents
- Overview
- OpenIndexMaps and GeoBlacklight
- Requirements and Recommendations
- 1. File coverage
- 2. File naming convention
- 3. File formats
- 4. Projections and coordinate systems
- 5. Element name character length
- 6. Element name format
- 7. Element name
- 8. Map extent geometry - vector creation
- 9. Bounding box - data entry
- 10. Holdings information - general
- 11. Physical holdings information
- 12. Digital holdings information
- 13. Sheet or frame number
- 14. Dates
- 15. Websites
- Element Names
- Set- and Flight-level Metadata
- Converting geospatial data to OpenIndexMap GeoJSON format
- Uploading to OpenIndexMaps
- Participants
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)