datacite-mapping 0.1.17.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 206495b36be88be8111bbb81c4634ea5e558134e
-  data.tar.gz: 87f325106c27c2c500e97885ff5422c445ec806f
+  metadata.gz: 8ca854763f76a711279af3353b9c5a9a5414058c
+  data.tar.gz: 3f99767c5394f6ae49e2ef60253d5064bfe33cd7
 SHA512:
-  metadata.gz: 646bbce9bea6dd89c1a8608ce1647cc9727ba022dca531d6f11b2478707813afec72b7c6681fcb5ea784bb02409f4caff55aa4c0911e3776b848cf696038bf82
-  data.tar.gz: d522fcb20188b4d41f0fb076120a00741926987ac1142703a3f1592b98693e058ea6f06438ead7f84e2b89e369760e6bff8725aeda14247206d59d6e67e10291
+  metadata.gz: 4161a49d7de22ed8528970d7a90afd4231ddd4e7a311aff1f836cbcd34cdaddde9b13719bd3fba239045dd8f636f4e5a226714354dab57bbf2f10cbe89e3a2d0
+  data.tar.gz: c4af15defeecf0ed3c9a36c3de15ce980f157b1baafac5d1b43a5d393c0067d3a3c3fdef7b0b9634cf116d191e899e920b9cdd88a719f0f3ca5a08c17f73c1ca

data/CHANGES.md

@@ -1,3 +1,36 @@
+## 0.2.0
+
+- Datacite 4.0 support:
+  - reading supports both Datacite 3 and Datacite 4
+  - writing now defaults to Datacite 4
+    - deprecated elements will produce a warning
+  - Datacite 3 support via `mapping: :datacite_3`
+    - invalid elements (`<geoLocationPolygon/>`, `<fundingReference>`)
+      will be dropped, with a warning
+    - [IGSN](http://igsn.github.io/overview/) identifiers will be converted to Handle identifiers
+- `language` and `xml:lang` attributes no longer default to `'en'` and are 
+  now fully optional.
+- `Date` now properly supports [RKMS-ISO8601](http://www.ukoln.ac.uk/metadata/dcmi/collection-RKMS-ISO8601/)
+  date ranges
+- Remove `Datacite::Mapping.log` in favor of `warn()`
+- Array fields (`subjects`, `contributors`, etc.) can no longer be set to nil; if set to 
+  nil they will instead return an empty array.
+- `:nonvalidating` mapping has been removed. Instead:
+  - `<subject/>` and `<description/>` tags without text are ignored on read, as are `<geoLocation>`
+    tags with no child elements.
+  - missing `<identifiers/>` and `<identifiers/>` with missing values are ignored on read, but
+    the `Resource` must be given a valid `Identifier` before writing it back out.
+
+## 0.1.18 (unreleased)
+
+- Datacite 4.0 support:
+  - read Datacite 4.0 `<fundingReference/>` tag (introduced in 0.1.17)
+  - read Datacite 4.0 `<geoLocationBox>` nodes with coordinates in child nodes
+    (`<southBoundLatitude>`, `<westBoundLongitude>`, `<northBoundLatitude>`, `<eastBoundLongitude>`)
+    rather than element text
+  - read Datacite 4.0 `<geoLocationPoint` nodes coordinates in child nodes
+    (`<pointLatitude>`, `<pointLongitude>`) rather than element text
+
 ## 0.1.17.2 (19 August 2016)
 
 - Filter out `<subject/>` tags without values

data/README.md

@@ -5,184 +5,127 @@
 [![Inline docs](http://inch-ci.org/github/CDLUC3/datacite-mapping.png)](http://inch-ci.org/github/CDLUC3/datacite-mapping)
 [![Gem Version](https://img.shields.io/gem/v/datacite-mapping.svg)](https://github.com/CDLUC3/datacite-mapping/releases)
 
-A library for mapping [DataCite XML](http://schema.datacite.org/meta/kernel-3/) to Ruby objects.
+A library for mapping [DataCite XML](http://schema.datacite.org/meta/kernel-4/) to Ruby objects,
+based on [xml-mapping](http://multi-io.github.io/xml-mapping/) and
+[xml-mapping_extensions](https://github.com/dmolesUC3/xml-mapping_extensions).
 Full API documentation on [RubyDoc.info](http://www.rubydoc.info/github/CDLUC3/datacite-mapping/master/frames).
 
-## Reading
+Supports [Datacite 4.0](https://schema.labs.datacite.org/meta/kernel-4.0/); backward-compatible with 
+[Datacite 3.1](https://schema.labs.datacite.org/meta/kernel-3/).
 
-```ruby
-require 'datacite/mapping'
+## Usage
 
-include Datacite::Mapping
+The core of the Datacite::Mapping library is the `Resource` class, corresponding to the root `<resource/>` element
+in a Datacite document.
 
-File.open('resource.xml', 'r') do |xml_file|
-  resource = Resource.parse_xml(xml_file)
-
-  creators = resource.creators
-  citation = ''
-  citation << creators.map(&:name).join('; ')
-  citation << ' '
-  citation << "(#{resource.publication_year})"
-  citation << ': '
-  title = resource.titles[0].value
-  citation << title
-  citation << (title.end_with?('.') ? ' ' : '. ')
-  citation << resource.publisher
-
-  puts("Citation: #{citation}")
-
-  abstract = resource.descriptions.find { |d| d.type = DescriptionType::ABSTRACT }
-  puts("Abstract: #{abstract.value}")
-end
-```
+### Reading
 
-Results:
+To create a `Resource` object from XML file, use `Resource.parse_xml` or `Resource.load_from_file`,
+depending on the data source:
 
-```
-Citation: Schumann, Kai; Völker, David; Weinrebe, Wilhelm Reiber (2011):
-Gridded results of swath bathymetric mapping of Disko Bay, Western
-Greenland, 2007-2008. PANGAEA - Data Publisher for Earth & Environmental
-Science
-
-Abstract: A ship-based acoustic mapping campaign was conducted at the exit
-of Ilulissat Ice Fjord and in the sedimentary basin of Disko Bay to the
-west of the fjord mouth. Submarine landscape and sediment distribution
-patterns are interpreted in terms of glaciomarine facies types that are
-related to variations in the past position of the glacier front. In
-particular, asymmetric ridges that form a curved entity and a large sill at
-the fjord mouth may represent moraines that depict at least two relatively
-stable positions of the ice front in the Disko Bay and at the fjord mouth.
-In this respect, Ilulissat Glacier shows prominent differences to the East
-Greenland Kangerlussuaq Glacier which is comparable in present size and
-present role for the ice discharge from the inland ice sheet. Two linear
-clusters of pockmarks in the center of the sedimentary basin seem to be
-linked to ongoing methane release due to dissociation of gas hydrates, a
-process fueled by climate warming in the Arctic realm.
-```
+| XML source        | Method to use             |
+| ----------------- | ------------------------- |
+| file path         | `Resource.load_from_file` |
+| `String`          | `Resource.parse_xml`      |
+| `IO`              | `Resource.parse_xml`      |
+| `REXML::Document` | `Resource.parse_xml`      |
+| `REXML::Element`  | `Resource.parse_xml`      |
 
-## Writing
+Example:
 
 ```ruby
 require 'datacite/mapping'
 include Datacite::Mapping
 
-# Based on "Example for a simple dataset"
-# http://schema.datacite.org/meta/kernel-3/example/datacite-example-dataset-v3.0.xml
+resource = Resource.load_from_file('datacite-example-full-v4.0.xml')
+# => #<Datacite::Mapping::Resource:0x007f97689e87a0 …
+
+abstract = resource.descriptions.find { |d| d.type = DescriptionType::ABSTRACT }
+# => #<Datacite::Mapping::Description:0x007f976aafa330 …
+abstract.value
+# => "XML example of all DataCite Metadata Schema v4.0 properties."
+```
+
+Note that Datacite::Mapping uses the `TypesafeEnum` gem to represent controlled vocabularies such
+as [ResourceTypeGeneral](http://www.rubydoc.info/github/CDLUC3/datacite-mapping/master/Datacite/Mapping/ResourceTypeGeneral)
+and [DescriptionType](http://www.rubydoc.info/github/CDLUC3/datacite-mapping/master/Datacite/Mapping/DescriptionType).
+
+### Writing
+
+In general, a `Resource` object must be provided with all required attributes on initialization.
+
+```ruby
 resource = Resource.new(
-  identifier: Identifier.new(value: '10.5072/D3P26Q35R-Test'),
+  identifier: Identifier.new(value: '10.5555/12345678'),
   creators: [
-    Creator.new(name: 'Fosmire, Michael'),
-    Creator.new(name: 'Wertz, Ruth'),
-    Creator.new(name: 'Purzer, Senay')
+    Creator.new(
+      name: 'Josiah Carberry',
+      identifier: NameIdentifier.new(
+        scheme: 'ORCID', 
+        scheme_uri: URI('http://orcid.org/'), 
+        value: '0000-0002-1825-0097'
+      ),
+      affiliations: [
+        'Department of Psychoceramics, Brown University'
+      ]
+    )
   ],
   titles: [
-    Title.new(value: 'Critical Engineering Literacy Test (CELT)')
+    Title.new(value: 'Toward a Unified Theory of High-Energy Metaphysics: Silly String Theory')
   ],
-  publisher: 'Purdue University Research Repository (PURR)',
-  publication_year: 2013,
-  subjects: [
-    Subject.new(value: 'Assessment'),
-    Subject.new(value: 'Information Literacy'),
-    Subject.new(value: 'Engineering'),
-    Subject.new(value: 'Undergraduate Students'),
-    Subject.new(value: 'CELT'),
-    Subject.new(value: 'Purdue University')
-  ],
-  language: 'en',
-  resource_type: ResourceType.new(resource_type_general: ResourceTypeGeneral::DATASET, value: 'Dataset'),
-  version: '1',
-  descriptions: [
-    Description.new(
-      type: DescriptionType::ABSTRACT,
-      value: 'We developed an instrument, Critical Engineering Literacy Test
-              (CELT), which is a multiple choice instrument designed to
-              measure undergraduate students’ scientific and information
-              literacy skills. It requires students to first read a
-              technical memo and, based on the memo’s arguments, answer
-              eight multiple choice and six open-ended response questions.
-              We collected data from 143 first-year engineering students and
-              conducted an item analysis. The KR-20 reliability of the
-              instrument was .39. Item difficulties ranged between .17 to
-              .83. The results indicate low reliability index but acceptable
-              levels of item difficulties and item discrimination indices.
-              Students were most challenged when answering items measuring
-              scientific and mathematical literacy (i.e., identifying
-              incorrect information).'
-    )
-  ]
+  publisher: 'Journal of Psychoceramics',
+  publication_year: 2008
 )
-
-puts resource.write_xml
+#  => #<Datacite::Mapping::Resource:0x007f9768958fb0 …
 ```
 
-Results:
-
-```xml
-<resource xmlns='http://datacite.org/schema/kernel-3' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:schemaLocation='http://datacite.org/schema/kernel-3 http://schema.datacite.org/meta/kernel-3/metadata.xsd'>
-  <identifier identifierType='DOI'>10.5072/D3P26Q35R-Test</identifier>
-  <creators>
-    <creator>
-      <creatorName>Fosmire, Michael</creatorName>
-    </creator>
-    <creator>
-      <creatorName>Wertz, Ruth</creatorName>
-    </creator>
-    <creator>
-      <creatorName>Purzer, Senay</creatorName>
-    </creator>
-  </creators>
-  <titles>
-    <title xml:lang='en'>Critical Engineering Literacy Test (CELT)</title>
-  </titles>
-  <publisher>Purdue University Research Repository (PURR)</publisher>
-  <publicationYear>2013</publicationYear>
-  <subjects>
-    <subject xml:lang='en'>Assessment</subject>
-    <subject xml:lang='en'>Information Literacy</subject>
-    <subject xml:lang='en'>Engineering</subject>
-    <subject xml:lang='en'>Undergraduate Students</subject>
-    <subject xml:lang='en'>CELT</subject>
-    <subject xml:lang='en'>Purdue University</subject>
-  </subjects>
-  <language>en</language>
-  <resourceType resourceTypeGeneral='Dataset'>Dataset</resourceType>
-  <version>1</version>
-  <descriptions>
-    <description xml:lang='en' descriptionType='Abstract'>
-      We developed an instrument, Critical Engineering Literacy Test (CELT),
-      which is a multiple choice instrument designed to measure undergraduate
-      students’ scientific and information literacy skills. It requires students
-      to first read a technical memo and, based on the memo’s arguments, answer
-      eight multiple choice and six open-ended response questions. We collected
-      data from 143 first-year engineering students and conducted an item
-      analysis. The KR-20 reliability of the instrument was .39. Item
-      difficulties ranged between .17 to .83. The results indicate low
-      reliability index but acceptable levels of item difficulties and item
-      discrimination indices. Students were most challenged when answering items
-      measuring scientific and mathematical literacy (i.e., identifying
-      incorrect information).
-    </description>
-  </descriptions>
-</resource>
+To create XML from a `Resource` object, use `Resource.write_xml`, `Resource.save_to_file`, or
+`Resource.save_to_xml`, depending on the destination:
+
+| XML destination   | Method to use           |
+| ----------------- | ----------------------- |
+| XML string        | `Resource.write_xml`    |
+| file path         | `Resource.save_to_file` |
+| `REXML::Element`  | `Resource.save_xml`     |
+
+```ruby
+resource.write_xml
+#  => "<resource xsi:schemaLocation='http://datacite.org/schema/kernel-4 …
 ```
 
-## Nonvalidating mapping (experimental)
+#### Namespace prefix
 
-Version 0.1.16 adds a `:nonvalidating` mapping, meant to deal with some issues we ran into with
-old, noncompliant data files. Specifically, it parses identifiers and subjects without values:
+To set a prefix for the Datacite namespace, use `Resource.namespace_prefix=`:
 
-```xml
-<identifier type="DOI"/>
-<subject schemeURI="http://www.nlm.nih.gov/mesh/" subjectScheme="MeSH"/>
+```ruby
+resource.namespace_prefix = 'dcs'
+resource.write_xml
+#  => "<dcs:resource xmlns:dcs='http://datacite.org/schema/kernel-4' …
 ```
 
-The former are imported with a nil value; the latter are skipped.
+### Datacite 3 compatibility
+
+In general, Datacite::Mapping is lax on read, accepting either Datacite 3 or Datacite 4 or a mix,
+and (mostly for historical reasons involving bad data its authors needed to parse) allowing some 
+deviations from the schema. By default, it writes Datacite 4, but can write Datacite 3 by passing
+an optional argument to any of the writer methods:
 
 ```ruby
-resource = Resource.parse_xml(xml_text, mapping: :nonvalidating)
-resource.write_xml(mapping: :nonvalidating)
+resource.write_xml(mapping: :datacite_3) # note schema URL below
+# => "<resource xsi:schemaLocation='http://datacite.org/schema/kernel-3
 ```
 
-This isn't meant to be exhaustive, only to handle some specific cases we ran into with importing
-old data. If you have additional cases, please file an issue, attaching sample documents, and
-we'll try to accommodate them.
+When using the `:datacite_3` mapping, the Datacite 4 `<geoLocationPolygon/>` and `<fundingReference/>` 
+elements, which are not supported in Datacite 3, will be dropped, with a warning. Any 
+`<relatedIdentifier/>` elements of type [IGSN](http://igsn.github.io/overview/) will be converted 
+to Handle identifiers with prefix 10273 (the prefix of the IGSN resolver).
+
+## Contributing
+
+Datacite::Mapping is released under an [MIT license](LICENSE.md). When submitting a pull request,
+please make sure the Rubocop style checks pass, as well as making sure unit tests pass with 100% 
+coverage; you can check these individually with `bundle exec rubocop` and `bundle exec rake:coverage`,
+or run the default rake task which includes both, `bundle exec rake`.
+
+
+

data/datacite-mapping.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_dependency 'typesafe_enum', '~> 0.1', '>= 0.1.7'
-  spec.add_dependency 'xml-mapping_extensions', '~> 0.4', '>= 0.4.5'
+  spec.add_dependency 'xml-mapping_extensions', '~> 0.4', '>= 0.4.7'
 
   spec.add_development_dependency 'bundler', '~> 1.7'
   spec.add_development_dependency 'equivalent-xml', '~> 0.6.0'

data/lib/datacite/mapping.rb

@@ -1,38 +1,23 @@
 require 'logger'
+require 'rexml/formatters/transitive' # unaccountably, xml/mapping doesn't do this
+require 'xml/mapping_extensions'
 
-# Module for working with the [DataCite metadata schema](https://schema.datacite.org/meta/kernel-3/index.html)
+# Module for working with the [DataCite metadata schema](https://schema.datacite.org/)
 module Datacite
   # Maps DataCite XML to Ruby objects
   module Mapping
 
-    Dir.glob(File.expand_path('../mapping/*.rb', __FILE__)).sort.each(&method(:require))
-
-    class << self
-      attr_writer :log
-    end
+    DATACITE_3_NAMESPACE = XML::MappingExtensions::Namespace.new(
+      uri: 'http://datacite.org/schema/kernel-3',
+      schema_location: 'http://schema.datacite.org/meta/kernel-3/metadata.xsd'
+    )
 
-    # Gets the logger for the module. Default logger logs to `$stdout`.
-    # @return [Logger] the logger
-    def self.log
-      self.log_device = $stdout unless @log
-      @log
-    end
+    DATACITE_4_NAMESPACE = XML::MappingExtensions::Namespace.new(
+      uri: 'http://datacite.org/schema/kernel-4',
+      schema_location: 'http://schema.datacite.org/meta/kernel-4/metadata.xsd'
+    )
 
-    # Sets the log device. Defaults to `$stdout`
-    # @param value [IO] the log device
-    def self.log_device=(value)
-      @log = new_logger(logdev: value)
-    end
-
-    private
+    Dir.glob(File.expand_path('../mapping/*.rb', __FILE__)).sort.each(&method(:require))
 
-    def self.new_logger(logdev:, level: Logger::DEBUG, shift_age: 10, shift_size: 1024 * 1024)
-      logger = Logger.new(logdev, shift_age, shift_size)
-      logger.level = level
-      logger.formatter = proc do |severity, datetime, progname, msg|
-        "#{datetime.to_time.utc} #{severity} -#{progname}- #{msg}\n"
-      end
-      logger
-    end
   end
 end

data/lib/datacite/mapping/alternate_identifier.rb

@@ -33,6 +33,8 @@ module Datacite
       root_element_name 'alternateIdentifier'
       text_node :type, '@alternateIdentifierType'
       text_node :value, 'text()'
+
+      fallback_mapping :datacite_3, :_default
     end
   end
 end

data/lib/datacite/mapping/contributor.rb

@@ -24,6 +24,7 @@ module Datacite
       # @!parse EDITOR = Editor
       new :EDITOR, 'Editor'
 
+      # @deprecated contributor type 'funder' is deprecated. Use {FundingReference} instead.
       # @!parse FUNDER = Funder
       new :FUNDER, 'Funder'
 
@@ -91,8 +92,9 @@ module Datacite
       end
 
       def name=(value)
-        fail ArgumentError, 'Name cannot be empty or nil' unless value && !value.empty?
-        @name = value
+        new_value = value && value.strip
+        fail ArgumentError, 'Name cannot be empty or nil' unless new_value && !new_value.empty?
+        @name = new_value
       end
 
       def type=(value)
@@ -115,6 +117,8 @@ module Datacite
       # @!attribute [rw] type
       #   @return [ContributorType] the contributor type. Cannot be nil.
       typesafe_enum_node :type, '@contributorType', class: ContributorType
+
+      fallback_mapping :datacite_3, :_default
     end
   end
 end

data/lib/datacite/mapping/creator.rb

@@ -1,4 +1,5 @@
 require 'xml/mapping'
+require 'datacite/mapping/read_only_nodes'
 require 'datacite/mapping/name_identifier'
 
 module Datacite
@@ -9,17 +10,32 @@ module Datacite
 
       # Initializes a new {Creator}.
       # @param name [String] The personal name of the creator, in the format `Family, Given`. Cannot be empty or nil.
+      # @param given_name [String, nil] The given name of the creator. Optional.
+      # @param given_name [String, nil] The family name of the creator. Optional.
       # @param identifier [NameIdentifier, nil] An identifier for the creator. Optional.
       # @param affiliations [Array<String>, nil] The creator's affiliations. Defaults to an empty list.
-      def initialize(name:, identifier: nil, affiliations: [])
+      def initialize(name:, given_name: nil, family_name: nil, identifier: nil, affiliations: [])
         self.name = name
+        self.given_name = given_name
+        self.family_name = family_name
         self.identifier = identifier
         self.affiliations = affiliations
       end
 
       def name=(value)
-        fail ArgumentError, 'Name cannot be empty or nil' unless value && !value.empty?
-        @name = value
+        new_value = value && value.strip
+        fail ArgumentError, 'Name cannot be empty or nil' unless new_value && !new_value.empty?
+        @name = new_value
+      end
+
+      def given_name=(value)
+        new_value = value && value.strip
+        @given_name = new_value
+      end
+
+      def family_name=(value)
+        new_value = value && value.strip
+        @family_name = new_value
       end
 
       def affiliations=(value)
@@ -30,6 +46,14 @@ module Datacite
       #   @return [String] The personal name of the creator, in the format `Family, Given`. Cannot be empty or nil.
       text_node :name, 'creatorName'
 
+      # @!attribute [rw] given_name
+      #   @return [String, nil] The given name of the creator. Optional.
+      text_node :given_name, 'givenName', default_value: nil
+
+      # @!attribute [rw] family_name
+      #   @return [String, nil] The family name of the creator. Optional.
+      text_node :family_name, 'familyName', default_value: nil
+
       # @!attribute [rw] identifier
       #   @return [NameIdentifier, nil] An identifier for the creator. Optional.
       object_node :identifier, 'nameIdentifier', class: NameIdentifier, default_value: nil
@@ -38,6 +62,12 @@ module Datacite
       #   @return [Array<String>, nil] The creator's affiliations. Defaults to an empty list.
       array_node :affiliations, 'affiliation', class: String, default_value: []
 
+      use_mapping :datacite_3
+
+      read_only_text_node :given_name, 'givenName', default_value: nil, warn_reason: '<givenName/> not supported in Datacite 3'
+      read_only_text_node :family_name, 'familyName', default_value: nil, warn_reason: '<familyName/> not supported in Datacite 3'
+
+      fallback_mapping :datacite_3, :_default
     end
   end
 end