Versions Compared

Old Version 30

changes.mady.by.user Ryan Miller

Saved on

compared with

New Version Current

changes.mady.by.user Scott Ritz

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents
stylecircle

Element Description

A service is a resource which can be used to transform data before downloading it (e.g. subset, reformat, re-project, etc.). Examples of services which are commonly used in the Earthdata community include OPeNDAP and Web Map Services (WMS). The Related URLs element, when accompanied by the 'use service api' sub-elements, can be used to link directly to these types of services.

If a service is available for a dataset, it is strongly encouraged that a link to the service be provided in the collection level metadata. It is also encouraged that a service metadata record be created for the service. Service metadata records provide additional capabilities and opportunities for users to search and access data in the Earthdata Search Client:

UMM-Service (UMM-S) Records

If a service is available for a dataset, it is strongly encouraged that a UMM-Service (UMM-S) metadata record be created for that service. This service record can then be associated with the collection level metadata record.  

UMM-S version 1.2 was released in July 2018, and UMM-S records can now be managed (i.e. created/populated/changed) via the Metadata Management Tool (MMT). Please see this link to the MMT User's Guide for details on how to manage UMM-S records in the MMT. 

There is also information available on how to ingest and search UMM-S records via the CMR API.

In the case that the creation of a UMM-S record is not feasible, it is still recommended that a link to the service be provided in the collection level metadata. Note that simply providing a link to a service in the collection level metadata does not provide the same capabilities offered by implementing a service metadata record.

The best practices that follow are for providing a link to a service in collection level metadata.

Best Practices

The Related URLs element, accompanied by 'Use Service API' sub-elements, is used to link to resources which can be used to subset and/or transform data and obtain it. This is different from a GET DATA URL, which relates to direct data access. For details concerning GET DATA URLs, please see the Related URLs (GET DATA) wiki page.

For general Related URL guidance (not specific to service links), please refer to the Related URLs wiki page.

For Non-NASA collections, the USE SERVICE API may be used to expose OpenSearch Description Document (OSDD) links to enable a collection's granules to be searched and discovered through the International Directory Network (IDN) search portal. For more information about how CMR utilizes OpenSearch, please refer to the CMR OpenSearch Documentation.

The USE SERVICE API Related URL metadata element allows for the linkage of a metadata record to a service. As mentioned on the Related URLs wiki page, there are several sub-elements which are used to identify the purpose of the URL. For USE SERVICE API links specifically, best practices for these elements include:

URL Content Type: The URL Content Type is a keyword which, at a high level, describes the content of a link. This is a controlled vocabulary field maintained as an enumeration list within the UMM-Common schema. For USE SERVICE API URLs, the URL Content Type should always be "DistributionURL."

URL Type: The URL Type is a keyword which specifies the content of a link. URL Type keywords are maintained in the Keyword Management System (KMS). For USE SERVICE API URLs, the URL Type should always be "USE SERVICE API."

URL Subtype: The URL Subtype is a keyword which further specifies the content of a link. Together, the URL Type and Subtype keywords create a keyword hierarchy which is used to identify the URL. Providing a Subtype for USE SERVICE API URLs is optional, but should be used when applicable. Valid Subtype keywords can be found here under the "Subtype" column. Specifically, any subtypes listed after the USE SERVICE API type keyword can be used to label service links. Definitions for these Subtypes can be found in the KMS.  

Description: While not required, it is highly recommended that a description be provided for each URL provided in the metadata. The description should be kept brief and explain to the user what type of service they are being linked to. The descriptions should be unique to the link. While descriptions can be repeated for the same type of URL across different metadata records, it is generally advised that the same description not be repeated within the same metadata record. I.e. the description should be used to further differentiate two USE SERVICE API URLs with the same URL Type and Subtype. 

There are several sub-elements specifically designated for USE SERVICE API URLs. The following provides definitions and best practices for each of the sub-elements:

RelatedUrls/GetService/Format: The format of the data provided via the associated URL. Providing the format is required??. Format is a controlled vocabulary field and should be chosen from the <insert GCMD data format keyword list>. If data is provided in a compressed file format, recommend listing the format of the data once it is uncompressed.   

RelatedUrls/GetService/MimeType: MIME stands for "Multipurpose Internet Mail Extensions". Mime types are used to identify the nature and format of files provided on the Internet, and are typically used by internet browsers in order to determine how to properly process or display a document or file. Providing the Mime Type element in the metadata helps ensure that the URL contents will be properly displayed on the Web. Providing a Mime Types is required for USE SERVICE API URLs. Mime Type is a controlled vocabulary field and should be chosen from the GCMD Mime Type keyword list. 

RelatedUrls/GetService/Protocol: The protocol is used to identify mechanisms/conventions for communication between different network devices. The Protocol element is a controlled vocabulary field maintained as an enumeration list within the UMM-Common schema.   

RelatedUrls/GetService/FullName: Do we still need this field?

RelatedUrls/GetService/DataID: Do we still need this field?  

RelatedUrls/GetService/DataType: Do we still need this field?

RelatedUrls/GetService/URI: Do we still need this field?


Examples:

URL: https://acdisc.gesdisc.eosdis.nasa.gov/opendap/Aqua_AIRS_Level3/AIRH3QPM.006/contents.html

URL Content Type: DistributionURL

URL Type: USE SERVICE API

URL Subtype: OPENDAP DATA

Description: Use the link to access data via the OPeNDAP protocol.

Format: HDF-EOS 

Mime Type: text/html 

Protocol: HTTPS

Full Name: Do we still need this field?

Data ID: Do we still need this field?

Data Type: Do we still need this field?

URI: Do we still need this field?


URL: https://disc1.gsfc.nasa.gov/daac-bin/wms_omi?service=WMS&version=1.1.1&request=GetCapabilities

URL Content Type: DistributionURL

URL Type: USE SERVICE API

URL Subtype: WEB MAP SERVICE (WMS)

Description: WEB MAP SERVICE (WMS) GetCapabilities request. 

Mime Type: text/xml

Protocol: HTTPS

Full Name: Do we still need this field?

Data ID: Do we still need this field?

Data Type: Do we still need this field?

URI: Do we still need this field?


URL: http://fedeo.esa.int/opensearch/description.xml?parentIdentifier=EOP:ESA:FEDEO:COLLECTIONS:CryoSat.products

URL Content Type: DistributionURL

URL Type: USE SERVICE API

URL Subtype: OpenSearch

Description: tag_key: opensearch.granule.osdd

Mime Type: application/opensearchdescription+xml

Element Specification

An unlimited amount of Related URLs may be listed (Cardinality: 0..*)

ModelElementTypeUsable Valid ValuesConstraintsRequired?CardinalityNotes
UMM-CommonRelatedUrls/URLStringn/a

1 - 1024 characters

Yes1The USE SERVICE API URL should point the user to a location where data can be subset or transformed before downloading.
UMM-CommonRelatedUrls/DescriptionStringn/a1 - 4000 charactersNo0..1It is strongly recommended that a description be provided for each URL.
UMM-CommonRelatedUrls/URLContentTypeEnumeration

DistributionURL


n/aYes1

"DistributionURL" is the only valid option for service links.

UMM-CommonRelatedUrls/TypeStringUSE SERVICE APIKMS controlledYes1"USE SERVICE API" should be provided as the Type.
UMM-CommonRelatedUrls/SubtypeStringGCMD URL Content Type 'Subtype' Keywords
KMS controlledNo0..1

The Type and Subtype are part of a keyword hierarchy specified in the KMS.

Any Subtype listed get after USE SERVICE API in the keyword list is a valid option. If none of the available Subtypes are appropriate for the URL, then it is okay to leave the Subtype field blank.

UMM-CommonRelatedUrls/GetService/FormatString
KMS controlledNo0..1
UMM-CommonRelatedUrls/GetService/MimeTypeStringGCMD Mime Type Keywords
KMS controlledYes, if applicable1
UMM-CommonRelatedUrls/GetService/ProtocolEnumeration

HTTP

HTTPS

FTP

FTPS

Not Provided

n/aYes, if applicable1

It is recommended that use of FTP and FTPS be phased out if possible.

UMM-CommonRelatedUrls/GetService/FullNameStringn/a1 - 80 charactersYes, if applicable1

Are we keeping the full name field?

UMM-CommonRelatedUrls/GetService/DataIDStringn/a1 - 80 charactersYes, if applicable1

Are we keeping the data ID field? "The data identifier of the data provided by the service." Typically, this is a file name. ← Providing a file name would only make sense for direct download

UMM-CommonRelatedUrls/GetService/DataTypeStringn/a1 - 80 charactersYes, if applicable1
UMM-CommonRelatedUrls/GetService/URI

Array

Composed of at least 1 String

n/a1 - 1024 characters (per string)No0..*

Metadata Validation and QA/QC

All metadata entering the CMR goes through the below process to ensure metadata quality requirements are met. All records undergo CMR validation before entering the system. The process of QA/QC is slightly different for NASA and non-NASA data providers. Non-NASA providers include interagency and international data providers and are referred to as the International Directory Network (IDN).

Lucidchart
rich-viewerfalse
autofittrue
nameCopy of Wiki Page Metadata Evaluation Workflow-1939-51df84
width1102
pages-to-display
id98e5dc28-3252-4209-953f-66f1378e1cf4
alignLeft
height299

Please see the expandable sections below for flowchart details.


Expand
titleGCMD Metadata QA/QC


Expand
titleCMR Validation

<>

Expand
titleARC Metadata QA/QC

ARC Priority Matrix

Priority CategorizationJustification

This element is categorized as highest priority when:

  • A USE SERVICE API URL is not provided in the metadata, but a service exists for the dataset.
  • The link labeled as USE SERVICE API is broken
  • The link is mislabeled as USE SERVICE API (i.e. the link does not lead to a service)
  • The USE SERVICE API link is labeled incorrectly (i.e. a service link is provided in the metadata but it is labeled as something else)
  • The USE SERVICE API link is provided via FTP
  • The USE SERVICE API link fails to take the user as directly as possible to the described data
  • The URL Type or Subtype provided does not align with the KMS
    • The Type or Subtype does not exist in KMS
    • The Type or Subtype is placed in the incorrect position of the hierarchy (e.g. USE SERVICE API should not be provided in the Subtype field, because it is categorized as a Type keyword in the KMS)
    • There is an invalid Type/Subtype relationship (e.g. Type: USE SERVICE API, Subtype: USER'S GUIDE, is not a valid combination in the KMS)
  • The URL Type or Subtype provided does not accurately describe the link
  • The mime type provided is incorrect
  • The data format provided is incorrect

This element is categorized as medium priority when:

  • The 'Description' element is left blank. It is highly recommended that a description be provided for each URL.
  • If a recommendation is made to add a new USE SERVICE API URL to the metadata, there will be accompanying yellow recommendations to add the appropriate URLContentType/URLType/Subtype elements.
    • Note: These recommendations are blue at the granule level, since the schema does not require Related URLs at the granule level 

This element is categorized as low priority when:

  • A description is repeated for multiple USE SERVICE API URLs
  • No mime type is provided for a service URL
  • If a recommendation is made to add a new USE SERVICE API URL to the metadata, there may be an accompanying blue recommendations to add the appropriate Mime Type 

The element is provided and follows all applicable criteria specified in the best practices section above.

ARC Automated Rules

URL: Information provided in the Related URLs/URL element will be passed through the URL checker

Description:

Dialect Mappings

Expand
titleDIF 9

DIF 9 (Note: DIF-9 is being phased out and will no longer be supported after 2018)

Expand
titleDIF 10

DIF 10

An unlimited amount of Related URLs may be listed (Cardinality: 0..*)

UMM-C ElementDIF 10 PathTypeUsable Valid ValuesConstraintsRequired in DIF 10?CardinalityNotes

Related_URL/URL

URI



No

0..*

The USE SERVICE API URL should point the user to a location where data files may be subset or transformed prior to download.


Related_URL/URL_Content_Type/TypeStringUSE SERVICE API

KMS controlled

No0..1"USE SERVICE API" should be provided as the Type.

Related_URL/URL_Content_Type/Subtype
StringGCMD URL Content Type 'Subtype' Keywords

KMS controlled


No0..1

The Type and Subtype are part of a keyword hierarchy specified in the KMS.

Any Subtype listed after USE SERVICE API in the keyword list is a valid option. If none of the available Subtypes are appropriate for the URL, then it is okay to leave the Subtype field blank.


Related_URL/DescriptionString

No0..1It is strongly recommended that a description be provided for each URL.

Related_URL/Mime_TypeStringGCMD Mime Type KeywordsKMS controlledNo0..1

Related_URL/ProtocolString

No0..1

Related_URL/TitleString

No0..1

Related_URL/Application_ProfileString

No0..1

Related_URL/FunctionString

No0..1


Example Mapping

Section

DIF 10

Column
width50%
<Related_URL>
  <URL_Content_Type>
    <Type>USE SERVICE API</Type>
    <Subtype>OPENDAP DATA</Subtype>
  </URL_Content_Type>
  <URL>https://acdisc.gesdisc.eosdis.nasa.gov/opendap/Aqua_AIRS_Level3/AIRH3QPM.006/contents.html</URL>
  <Mime_Type>text/html</Mime_Type>
  <Protocol>HTTPS</Protocol>
  <Description>Use the link to access data via the OPeNDAP protocol.</Description>
</Related_URL>
Column
width50%

UMM

No Format
RelatedUrls: [
  {
    Description: "Use the link to access data via the OPeNDAP protocol.",
    URLContentType: "DistributionURL",
    Type: "USE SERVICE API",
    Subtype: "OPENDAP DATA",
    URL:  "https://acdisc.gesdisc.eosdis.nasa.gov/opendap/Aqua_AIRS_Level3/AIRH3QPM.006/contents.html",
   -GetData: {
      MimeType: "text/html",
      Protocol: "HTTPS"
    }
  }
]
Expand
titleECHO 10

ECHO 10

UMM-C ElementECHO 10 PathTypeConstraintsRequired in ECHO10?CardinalityNotes

/Collection/String


No0..1

/Collection/String


No0..1


Enumeration Mapping

ECHO 10

Translation

Direction

UMM
Not Applicable↔Not Applicable

Example Mapping

Section
Column
width50%

ECHO 10

No Format
ADD EXAMPLE
Column
width50%

UMM

No Format
RelatedUrls: [
  {
    Description: "Use the link to access data via the OPeNDAP protocol.",
    URLContentType: "DistributionURL",
    Type: "USE SERVICE API",
    Subtype: "OPENDAP DATA",
    URL:  "https://acdisc.gesdisc.eosdis.nasa.gov/opendap/Aqua_AIRS_Level3/AIRH3QPM.006/contents.html",
   -GetData: {
      MimeType: "text/html",
      Protocol: "HTTPS"
    }
  }
]



Expand
titleISO 19115-2 MENDS

ISO 19115-2 MENDS

UMM-C ElementISO 19115-2 MENDS PathTypeNotes


String





String


String


String




String


String





Enumeration/Code List Mapping

ISO MENDS

Translation

Direction

UMM
inapplicable↔Not Applicable

Example Mapping

Section
Column
width50%

ISO 19115-2 MENDS

No Format
ADD EXAMPLE
Column
width50%

UMM

No Format
RelatedUrls: [
  {
    Description: "Use the link to access data via the OPeNDAP protocol.",
    URLContentType: "DistributionURL",
    Type: "USE SERVICE API",
    Subtype: "OPENDAP DATA",
    URL:  "https://acdisc.gesdisc.eosdis.nasa.gov/opendap/Aqua_AIRS_Level3/AIRH3QPM.006/contents.html",
   -GetData: {
      MimeType: "text/html",
      Protocol: "HTTPS"
    }
  }
]



Expand
titleISO 19115-2 SMAP

ISO 19115-2 SMAP

UMM-C Element

ISO 19115-2 SMAP Path

TypeNotes


String





String


String


String




String


String





Enumeration/Code List Mapping

ISO SMAP

Translation

Direction

UMM
inapplicable↔Not Applicable

Example Mapping

Section
Column
width50%

ISO 19115-2 SMAP

No Format
ADD EXAMPLE
Column
width50%

UMM

No Format
RelatedUrls: [
  {
    Description: "Use the link to access data via the OPeNDAP protocol.",
    URLContentType: "DistributionURL",
    Type: "USE SERVICE API",
    Subtype: "OPENDAP DATA",
    URL:  "https://acdisc.gesdisc.eosdis.nasa.gov/opendap/Aqua_AIRS_Level3/AIRH3QPM.006/contents.html",
   -GetData: {
      MimeType: "text/html",
      Protocol: "HTTPS"
    }
  }
]



UMM Migration

None

Excerpt
hiddentrue

Future Mappings

Expand
titleISO 19115-1

ISO 19115-1

UMM-C Element

ISO 19115-1 Path

TypeNotes


String



String



String


String



String






Enumeration/Code List Mapping

ISO 19115-1

Translation

Direction

UMM
inapplicable↔Not Applicable
Section
Column
width50%

ISO 19115-1

No Format
ADD EXAMPLES
Column
width50%

UMM

No Format
RRelatedUrls: [
  {
    Description: "Use the link to access data via the OPeNDAP protocol.",
    URLContentType: "DistributionURL",
    Type: "USE SERVICE API",
    Subtype: "OPENDAP DATA",
    URL:  "https://acdisc.gesdisc.eosdis.nasa.gov/opendap/Aqua_AIRS_Level3/AIRH3QPM.006/contents.html",
   -GetData: {
      MimeType: "text/html",
      Protocol: "HTTPS"
    }
  }
]

History

UMM Versioning

VersionDateWhat Changed
1.15.512/3/2020No changes were made for Related URLs-Use Service during the transition from version 1.15.4 to 1.15.5
1.15.49/18/2020No changes were made for Related URLs-Use Service during the transition from version 1.15.3 to 1.15.4
1.15.37/1/2020No changes were made for Related URLs-Use Service during the transition from version 1.15.2 to 1.15.3
1.15.25/20/2020No changes were made for Related URLs-Use Service during the transition from version 1.15.1 to 1.15.2
1.15.13/25/2020No changes were made for Related URLs-Use Service during the transition from version 1.15.0 to 1.15.1
1.15.02/26/2020No changes were made for Related URLs-Use Service during the transition from version 1.14.0 to 1.15.0
1.14.010/21/2019No changes were made for Related URLs-Use Service during the transition from version 1.13.0 to 1.14.0
1.13.004/11/2019No changes were made for Related URLs-Use Service during the transition from version 1.12.0 to 1.13.0.
1.12.001/22/2019No changes were made for Related URLs-Use Service during the transition from version 1.11.0 to 1.12.0.
1.11.011/28/2018No changes were made for Related URLs-Use Service during the transition from version 1.10.0 to 1.11.0.
1.10.005/02/2018During the transition from version 1.9.0 to 1.0.0, the sub element 'Format' was added, which provides the format of the data accessed via the associated URL.
1.9.0

ARC Documentation

VersionDateWhat ChangedAuthor
1.007/26/2018Recommendations/priority matrix transferred from internal ARC documentation to wiki spaceJeanne' le Roux