Community:NDR/addMetadata

From NSDLWiki

Jump to: navigation, search

Contents

[hide]

addMetadata

Create a Metadata object (see ObjectTypes) in the NDR.

Request URL

http://ndr.nsdl.org/api/addMetadata
Must be an HTTP POST request.

Arguments

  • inputXML (required) - contains metadata supplied by a MetadataProvider about a given NDR object, as well as identifiers and relationships for the Metadata object. For metadata harvested via the Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH - see http://www.openarchives.org/OAI/openarchivesprotocol.html), inputXML could include all the metadata formats available for an OAI item. Individual metadata formats may also be added, removed, or replaced individually through the modifyMetadata request.

    • Properties
      • uniqueID (required) - An identifier that is unique for all Metadata objects supplied by a single MetadataProvider.
      • itemId (optional) - currently (2006-12) this must be provided if the metadata is to be exposed via the NDR's OAI server. This must be a valid NSDL OAI identifier, meaning it must start "oai:nsdl.org:" and it must adhere to the OAI guidelines for OAI identifiers (http://www.openarchives.org/OAI/2.0/guidelines-oai-identifier.htm). It must also be unique for each metadata object in the NDR. Best practice is to prepend "oai:nsdl.org:" to the uniqueID.

    • Relationships
      • metadataFor (required) - the handle of an NDR object the Metadata describes. This relationship is repeatable if the Metadata describes more than one NDR object (e.g. there are two valid resouce identifiers in the metadata).
      • metadataProvidedBy (required) - the handle of the MetadataProvider object representing the source of the metadata in this request.

    • Datastreams
      • format (required) - There must be at least one metadata format supplied; multiple formats may be supplied. Includes a "type" attribute designating the format-label of the metadata. The format-label must be a known type; as of 2006-12-08, known types include "nsdl_dc" (for NSDL normalized qualified Dublin Core), "oai_dc" (for simple Dublin Core derived from the normalized qualified Dublin Core nsdl_dc format) or "native_(xxx)" for raw, un-normalized metadata, such as "native_oai_dc" or "native_nsdl_dc".
        • meta (required) - each format supplied must contain a complete, schema-valid metadata record. The meta element must must contain XML that complies with another schema, such as http://ns.nsdl.org/schemas/nsdl_dc/nsdl_dc_v1.02.xsd or http://www.openarchives.org/OAI/2.0/oai_dc.xsd. In other words, the meta element must have a single child element that can be interpreted as the root of a schema-valid XML document - all namespace declarations and schema locations must be specified in the children of the meta element.
        • info (currently required) - Information to be exposed in OAI "abouts" bundled with the NDR's OAI server exposure of this metadata. The info element must contain the following (see the XML schema http://ns.nsdl.org/schemas/ndr/request_v1.00.xsd for more information):
          • nsdlAboutCategory - either "item" or "collection" (this is a vestigial field, slated for deprecation and/or removal).
          • repositoryPrimaryIdentifier - The identifier within the metadata which is to be considered the "primary" identifier. For example, if there are two <dc:identifier> fields in metadata that describes a resource, then one of them must be chosen as the "primary" identifier in this metadata. Best practice: a valid URL present in the metadata (you may not choose an identifier that is not present in the provided metadata).
          • link (currently important to the NSDL search service) - the NDR OAI identifier of the OAI metadata describing the NDR Aggregation object which has this Metadata object's described object as a member. This will be the same value for all Metadata objects from a single MetadataProvider. Currently, this should be determined by the following steps: 1) get the handle of the MetadataProvider object responsible for this Metadata from the metadataProvidedBy relationship. 2) get the handle of the Aggregator object describing the aggregation implied by the MetadataProvider from the aggregatedBy relationship in the Aggregator object. 3) get the handle of the Metadata object describing the Aggregator by using the find command to look for a Metadata object that has metadataFor relationship to the Aggregator object. 4) The itemId property of the Metadata object describing the Aggregator (describing the aggregation for the MetadataProvider which is the soure of this Metadata object, which lives in the house that Jack built) is the NDR OAI identifier to be used as the value for this link.
          • harvestDate - when the metadata was harvested, as a UTC datestamp (GMT, in datetime "Z" format)
          • harvestHarvestType - how this metadata was harvested, from enumerated list (e.g. "OAI2.0", "other").
          • harvestDatasourcePublic - flag indicating whether the data source of the harvest is publically available or not (true/false).
          • harvestDatasource - URL for the metadata provider's service (e.g. the baseURL of an OAI data provider). This must be a URI, and may not be empty. If necessary, enter a meaningful fake value, such as: http://fake.baseurl/metadataNotHarvested
          • harvestIdentifier - the metadata provider's unique ID for this metadata. (e.g. the metadata provider's OAI identifier). This should be the same as the value of the uniqueID property.
          • harvestRecordDatestamp - when the metadata was last updated, as a UTC datestamp (GMT, in datetime "Z" format). This is equivalent to the datestamp element of the harvested record's OAI header.
          • metadataNamespace> - XML namespace URI of this format's metadata.


Below is example inputXML for a Metadata object to be added. This Metadata object corresponds to the OAI item with identifier "oai:myDomain:666". The metadata included here describes the NDR Resource object identified by handle 2200/20061111T. This metadata originates from the MetadataProvider with NDR handle 2200/5005. A single metadata format is provided; it is of type -nsdl_dc- and contains an XML schema valid document with root element <nsdl_dc:nsdl_dc> with the proper XML namespace declarations and schema location indicated. The info element has been populated with appropriate information for use in NDR OAI about fields. Note that the command is understood to be "add" (rather than "replace" or "delete") so the inputXML does not require a command as the first child of the <properties>, <relationships>, or <data> elements. 
<?xml version="1.0" encoding="UTF-8"?>
<inputXML 
    xmlns="http://ns.nsdl.org/ndr/request_v1.00/" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://ns.nsdl.org/ndr/request_v1.00/ http://ns.nsdl.org/schemas/ndr/request_v1.00.xsd" 
    schemaVersion="1.00.000">
  <metadata>
    <properties>
      <uniqueID>oai:myDomain:666</uniqueID>
    </properties>
    <relationships>
      <metadataFor>2200/20061111T</metadataFor>
      <metadataProvidedBy>2200/5005</metadataProvidedBy>
    </relationships>
    <data>
      <format type="nsdl_dc">
        <meta>
          <nsdl_dc:nsdl_dc 
              xmlns:nsdl_dc="http://ns.nsdl.org/nsdl_dc_v1.02/" 
              schemaVersion="1.02.000" xmlns:dc="http://purl.org/dc/elements/1.1/" 
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
              xsi:schemaLocation="http://ns.nsdl.org/nsdl_dc_v1.02/ http://ns.nsdl.org/schemas/nsdl_dc/nsdl_dc_v1.02.xsd">
            <dc:title>My life: a Monster's Story.</dc:title>
            <dc:description>The story of Frankenstein.</dc:description>
            <dc:identifier>http://www.frankenstein.org/autobiography</dc:identifier>
            <dc:creator>Baron Von Frankenstein</dc:creator>
            <dc:author>Mary Shelly</dc:author>
          </nsdl_dc:nsdl_dc>
        </meta>
        <info>
          <nsdlAboutCategory>collection</nsdlAboutCategory>
          <repositoryPrimaryIdentifier>http://www.frankenstein.org/autobiography</repositoryPrimaryIdentifier>
          <link>oai:nsdl.org:nsdl:3000:nsdl:4002</link>
          <harvestDate>2005-07-25T16:50:17Z</harvestDate>
          <harvestHarvestType>OAI2.0</harvestHarvestType>
          <harvestDatasourcePublic>true</harvestDatasourcePublic>
          <harvestDatasource>http://frodoLives.org/oai</harvestDatasource>
          <harvestIdentifier>oai:crs.nsdl.org:4002</harvestIdentifier>
          <harvestRecordDatestamp>2002-07-03T20:31:21Z</harvestRecordDatestamp>
          <metadataNamespace>http://ns.nsdl.org/nsdl_dc_v1.02/</metadataNamespace>
        </info>
      </format>
    </data>
  </metadata>
</inputXML>

Response Fields

  • handle - the NDR handle for the new Metadata object

Response Example 

<?xml version="1.0" encoding="UTF-8"?>
<NSDLDataRepository 
    schemaVersion="1.00.000" 
    xmlns="http://ns.nsdl.org/ndr/response_v1.00/" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://ns.nsdl.org/ndr/response_v1.00/ http://ns.nsdl.org/schemas/ndr/response_v1.00.xsd">
  <responseTime>2005-10-26T18:42:05Z</responseTime>
  <requestURL>http://ndr.nsdl.org/api/addMetadata</requestURL>
  <resultData>
    <handle>2200/200605071304123T</handle>
  </resultData>
</NSDLDataRepository>

API Links:

Retrieved from "../index.php/Community:NDR/addMetadata"
Personal tools