USGIN URI Syntax

As described above, USGIN URIs identify resources and use HTTP-compatible syntax to produce representations of said resources in web browsers. A USGIN URI can be broken down into a number of component tokens, which are represented in simplified form below:

http://host/uri-gin/authority/resource-type/resource-specific/

The tokens that comprise USGIN URIs are as follows:

  • http:// This token specifies the HTTP protocol for the URI.
  • host/ This token is a standard World-Wide Web domain name that is used to locate a particular server that has the necessary software to dereference the URI and return a representation of the resource identified by the URI. Currently, all USGIN URIs are dereferenced through the host located by:
    resources.usgin.org
  • uri-gin/ By USGIN convention, this token indicates that the URI is a USGIN URI. All URI components following this token are terminal components of the USGIN URI. The terminal components of the USGIN URI often reflect or incorporate existing resource identifiers that are not URIs, such as American Petroleum Institute (API) numbers. This is only practical, as existing resource identifiers are often sufficient for the purposes of USGIN - why reinvent the wheel?
  • authority/ This token identifies the local naming agent responsible for issuing and maintaining any resource identifiers that are present within the the terminal components of the USGIN URI. For example, if a USGIN URI identifies an oil well with an API number, and if the URI incorporates that API number into the URI, then the authority/ token would reflect the authority responsible for issuing and maintaining API numbers: the American Petroleum Institute (or their agent in a particular state), abbreviated API. Examples of authority abbreviations in the context of USGIN URIs are as follows:
    • American Petroleum Institute (API): http://host/uri-gin/api/
    • United States Geological Survey (USGS): http://host/uri-gin/usgs/
    • Arizona Geological Survey (AZGS): http://host/uri-gin/azgs/
    • Department of the Interior (DOI): http://host/uri-gin/doi/
    • Department of Energy (DOE): http://host/uri_gin/doe/
  • resource-type/ This token indicates the type of resource identified by the URI. Note that this token may itself be hierarchical, with resource subtypes delimited by the path separator character ‘/’ Sample USGIN URI conventions can be found below:
    • Active or quaternary fault resource: http://host/uri-gin/authority/fault/
    • Borehole temperature resource: http://host/uri-gin/authority/bhtemp/
    • Thermal spring resource: http://host/uri-gin/authority/thermalspring/
    • Well header resource: http://host/uri-gin/authority/well/
  • resource-specific/ This token uniquely identifies a resource. Literally anything is possible within this component of the USGIN URI, although USGIN recommends constructing the string systematically, using existing resource identifiers and URL-safe characters. A list of URL-safe characters for resource-specific strings is as follows:
    • 0-9
    • a-z
    • A-Z
    • /
    • - (dash)
    • _ (underscore)

Consequently, a finished URI that follows USGIN specifications and identifies a specific car (vehicular resource) might appear as follows:

http://resources.cars.org/uri-gin/azdmv/vehicle/ABC123

Likewise, a finished URI that follows USGIN specifications and identifies a military aircraft (military resource) might appear as follows:

http://resources.airforce.gov/uri-gin/usaf/vehicle/aircraft/f22/1234567

This concludes the USGIN URI tutorial.