Community:NDR/modifyMetadata

From NSDLWiki

Jump to: navigation, search

Contents

[hide]

modifyMetadata

Modify an existing Metadata object (see ObjectTypes) in the NDR.

Request URL

http://ndr.nsdl.org/api/modifyMetadata/[handle]
where [handle] is the handle for an existing Metadata object.
Must be an HTTP POST request.

Arguments

(the Metadata object handle is at the end of the requestURL)
  • inputXML (required) - while inputXML is required, no specific element is required for the modifyMetadata request. Only data desired to be added, deleted, or replaced should be included. The inputXML may lack or contain empty <properties>, <relationships> and/or <data> elements.

    • Properties
      • [command] (optional) - see below.
        • uniqueID (optional) - if this is provided (and command is not "delete"), it will replace the previous uniqueID in the Metadata object. It must be an identifier that is unique for all Metadata objects supplied by a single MetadataProvider. The NDR will ensure that Metadata objects have exactly one uniqueID.
        • itemId (optional) - if this is provided (and command is not "delete"), it will replace the previous itemId in the Metadata object. This property must be present in the Metadata object if the metadata is to be exposed via the NDR's OAI server. The value 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 for the value of itemId. Best practice is to modify the itemId property in synch with modifications to the uniqueID property. The NDR will ensure that Metadata objects have exactly one itemId.

    • Relationships
      • [command] (strongly recommended, but optional) - best practice is to use only explicit "add" or "delete". The "replace" command will only succeed if the Metadata object has less than two existing like relationships. See below.
        • metadataFor (optional) - 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 (optional) - the handle of the MetadataProvider object representing the source of the metadata in this NDR Metadata object. The NDR will ensure that Metadata objects have exactly one metadataProvidedBy relationship.

    • Datastreams
      • [command] (optional) - see below.
        • format (optional) - zero, one or more metadata formats may be supplied. If a metadata format is provided, it must have a "type" attribute, designating the format-label of the metadata. The format-label must be a known type; as of 2006-04-03, known types include "nsdl_dc" (for NSDL normalized qualified Dublin Core), "oai_dc" (for NSDL normalized 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". Metadata formats provided here will be matched against existing formats in the Metadata object. If the command is "add" or "replace" and there is a match, the format provided here will replace the existing version of the format. If there is not a match (the format is not already present in the Metadata object), it will be added to the Metadata object. The NDR will ensure that Metadata objects have no more than one datastream for a single format, and have exactly one of each of the normalized format datastreams, nsdl_dc and oai_dc, and exactly one info datastream.
          • meta (required, unless command is "delete") - 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 (optional) - Information to be exposed in OAI "abouts" bundled with the NDR's OAI server exposure of this metadata. There currently must be exactly one info datastream in a Metadata object. The NDR will ensure that Metadata objects have exactly one info datastream. 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.
            • 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.


where [command] is one of:

  • add - add the contained properties, relationships or datastreams to the object.
  • delete - remove the contained properties, relationships or datastreams from the object.
  • modify (default) - if the contained properties, relationships or datastreams already exist in the object, replace them with what is contained here. If the contained properties, relationships or datastreams do NOT exist in the object, add them.


Below is example inputXML for a Metadata object to be modified. The metadata provider changed its metadata identifier scheme, so the metadata provider's unique id for this metadata is now "oai:ourDomain:666." No relationships between this Metadata object and its MetadataProvider or between this Metadata object and the NDR object it describes are being changed. 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 supplied nsdl_dc metadata will replace the existing nsdl_dc metadata format for this Metadata object, if that format exists. Otherwise, the nsdl_dc format will be added to the Metadata object. The info element has been populated with appropriate information for use in NDR OAI about fields. 
<?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:ourDomain:666</uniqueID>
    </properties>
    <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.</nowiki></dc:title>
            <dc:description>The story of Frankenstein, blah blah blah.</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>
See also AddMetadata.

Response Fields

  • handle - the NDR handle for the 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/modifyMetadata/2200/200605091309003T</requestURL>
  <resultData>
    <handle>2200/200605091309003T</handle>
  </resultData>
</NSDLDataRepository>

API Links:

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