adiwg-mdtranslator 1.4.0 → 2.0.0rc2

data/lib/adiwg/mdtranslator/internal/module_coordinates.rb

@@ -1,18 +1,20 @@
 # repack coordinates
 
 # History:
-# 	Stan Smith 2013-11-07 original script
-# 	Stan Smith 2013-11-13 added getDimension
-#   Stan Smith 2014-05-23 added getLevels
-#   Stan Smith 2014-12-15 refactored to handle namespacing readers and writers
-#   Stan Smith 2015-06-22 replace global ($response) with passed in object (responseObj)
-#   Stan Smith 2015-07-14 refactored to remove global namespace constants
+#   Stan Smith 2016-11-10 added computedBbox computation
 #   Stan Smith 2015-07-16 moved module_coordinates from mdJson reader to internal
+#   Stan Smith 2015-07-14 refactored to remove global namespace constants
+#   Stan Smith 2015-06-22 replace global ($response) with passed in object (responseObj)
+#   Stan Smith 2014-12-15 refactored to handle namespacing readers and writers
+#   Stan Smith 2014-05-23 added getLevels
+# 	Stan Smith 2013-11-13 added getDimension
+# 	Stan Smith 2013-11-07 original script
 
 module AdiwgCoordinates
 
     # repack coordinate array into single string for ISO
-    def self.unpack(aCoords, responseObj)
+    def self.stringifyCoords(aCoords, responseObj)
+
         s = ''
         i = 0
         coordCount = aCoords.length
@@ -30,10 +32,12 @@ module AdiwgCoordinates
         end
 
         return s
+
     end
 
     # get the number of dimensions in a coordinate array
     def self.getDimension(aCoords)
+
         if aCoords[0].kind_of?(Array)
             coordDim = getDimension(aCoords[0])
         else
@@ -41,15 +45,127 @@ module AdiwgCoordinates
         end
 
         return coordDim
+
     end
 
     # get the number of levels in the coordinate array
     def self.getLevels(aCoords)
+
         i = 1
         if aCoords[0].kind_of?(Array)
             i = i + getLevels(aCoords[0])
         end
         return i
+
+    end
+
+    # compute bounding box
+    def self.computeBbox(aGeo)
+
+        # find all the eastings (x) and northings (y) in the GeoJSON object
+        aNorthings = []
+        aEastings = []
+        aGeo.each do |hGeo|
+            unpackGeometry(hGeo, aNorthings, aEastings)
+        end
+
+        # find most north/south points
+        north = aNorthings.max
+        south = aNorthings.min
+
+        # find most east/west spanning the meridian
+        eastM = aEastings.max
+        westM = aEastings.min
+
+        # find most east/west spanning the anti-meridian
+        positiveEast = []
+        negativeEast = []
+        aEastings.each do |east|
+            negativeEast << east if east < 0.0
+            positiveEast << east if east >= 0.0
+        end
+        eastAM = negativeEast.max
+        westAM = positiveEast.min
+
+        # if eastings are all positive or all negative no meridian was spanned
+        if positiveEast.empty? || negativeEast.empty?
+            east = eastM
+            west = westM
+        else
+            # choose which meridian was spanned based on smaller edge-to-edge distance
+            distanceM = eastM - westM
+            distanceAM = (180 + eastAM) + (180 - westAM)
+            if distanceM <= distanceAM
+                # this spanned to  meridian
+                east = eastM
+                west = westM
+            else
+                # this spanned tne anti-meridian
+                east = eastAM
+                west = westAM
+            end
+        end
+
+        bBox = {}
+        bBox[:westLongitude] = west
+        bBox[:eastLongitude] = east
+        bBox[:southLatitude] = south
+        bBox[:northLatitude] = north
+
+        return bBox
+
+    end
+
+    # compute bounding box
+    def self.unpackGeometry(hGeo, aNorthings, aEastings)
+
+        # geometry objects
+        type = hGeo[:type]
+        if %w{ Point LineString Polygon MultiPoint MultiLineString MultiPolygon }.one? { |word| word == type }
+            unpackCoords(hGeo[:coordinates], aNorthings, aEastings)
+        end
+
+        # geometry collections
+        if hGeo[:type] == 'GeometryCollection'
+            hGeo[:geometryObjects].each do |aGeoObj|
+                unpackCoords(aGeoObj[:coordinates], aNorthings, aEastings)
+            end
+        end
+
+        # features
+        if hGeo[:type] == 'Feature'
+            featureType = hGeo[:geometryObject][:type]
+            if featureType == 'GeometryCollection'
+                unpackGeometry(hGeo[:geometryObject], aNorthings, aEastings)
+            else
+                unpackCoords(hGeo[:geometryObject][:coordinates], aNorthings, aEastings)
+            end
+        end
+
+        # feature collections
+        if hGeo[:type] == 'FeatureCollection'
+            hGeo[:features].each do |hFeature|
+                unpackGeometry(hFeature, aNorthings, aEastings)
+            end
+        end
+
+    end
+
+    # compute bounding box
+    def self.unpackCoords(aCoords, aNorthings, aEastings)
+        if aCoords[0].kind_of?(Array)
+            aCoords.each do |aTuple|
+                unpackCoords(aTuple, aNorthings, aEastings)
+            end
+        else
+            addPoint(aCoords, aNorthings, aEastings)
+        end
+    end
+
+    # compute bounding box
+    def self.addPoint(aPoint, aNorthings, aEastings)
+        aEastings << aPoint[0]
+        aNorthings << aPoint[1]
     end
 
 end

data/lib/adiwg/mdtranslator/internal/module_dateTimeFun.rb

@@ -95,4 +95,49 @@ module AdiwgDateTimeFun
         return s
     end
 
+    def self.writeDuration(hDuration)
+        # format P[n]Y[n]M[n]DT[n]H[n]M[n]S
+        # example P1DT12H
+        sDuration = 'P'
+
+        unless hDuration[:years] == 0
+            sDuration += hDuration[:years].to_s + 'Y'
+        end
+
+        unless hDuration[:months] == 0
+            sDuration += hDuration[:months].to_s + 'M'
+        end
+
+        unless hDuration[:days] == 0
+            sDuration += hDuration[:days].to_s + 'D'
+        end
+
+        haveTime = false
+
+        unless hDuration[:hours] == 0
+            unless haveTime
+                sDuration += 'T'
+                haveTime = true
+            end
+            sDuration += hDuration[:hours].to_s + 'H'
+        end
+
+        unless hDuration[:minutes] == 0
+            unless haveTime
+                sDuration += 'T'
+                haveTime = true
+            end
+            sDuration += hDuration[:minutes].to_s + 'M'
+        end
+
+        unless hDuration[:seconds] == 0
+            unless haveTime
+                sDuration += 'T'
+            end
+            sDuration += hDuration[:seconds].to_s + 'S'
+        end
+
+        return sDuration
+    end
+
 end

data/lib/adiwg/mdtranslator/readers/mdJson/mdJson_reader.rb

@@ -1,214 +1,119 @@
-# Reader - ADIwg JSON V1 to internal data structure
+# mdJson reader - process and direct mdJson ingest to internal data structure
 
 # History:
-# 	Stan Smith 2013-08-09 original script
-# 	Stan Smith 2013-08-19 split out contacts to module_contacts
-# 	Stan Smith 2013-08-23 split out metadata to module_metadata
-#	Stan Smith 2014-04-23 add json schema version to internal object
-#   Stan Smith 2014-06-05 capture an test json version
-#   Stan Smith 2014-07-03 resolve require statements using Mdtranslator.reader_module
-#   Stan Smith 2014-07-08 moved json schema version testing to 'adiwg_1_get_version'
-#   Stan Smith 2014-08-18 add json name/version to internal object
-#   Stan Smith 2014-12-01 add data dictionary
-#   Stan Smith 2014-12-03 changed class name to MdJsonReader from AdiwgJsonReader
-#   Stan Smith 2014-12-11 refactored to handle namespacing readers and writers
-#   Stan Smith 2015-06-12 added method to lookup contact in contact array
-#   Stan Smith 2015-06-22 replace global ($response) with passed in object (responseObj)
-#   Stan Smith 2015-07-14 refactored to remove global namespace constants
+#   Stan Smith 2016-11-12 refactor for mdTranslator 2.0
+#   Stan Smith 2016-10-09 modify 'findContact' to also return contact index and type
+#   Stan Smith 2016-10-07 refactored 'readerModule' to remove mdJson version checking
 #   Stan Smith 2015-07-14 added support for mdJson version numbers
+#   Stan Smith 2015-07-14 refactored to remove global namespace constants
+#   Stan Smith 2015-06-22 replace global ($response) with passed in object (hResponseObj)
+#   Stan Smith 2015-06-12 added method to lookup contact in contact array
+#   Stan Smith 2014-12-11 refactored to handle namespacing readers and writers
+#   Stan Smith 2014-12-03 changed class name to MdJsonReader from AdiwgJsonReader
+#   Stan Smith 2014-12-01 add data dictionary
+#   Stan Smith 2014-08-18 add json name/version to internal object
+#   Stan Smith 2014-07-08 moved json schema version testing to 'adiwg_1_get_version'
+#   Stan Smith 2014-07-03 resolve require statements using Mdtranslator.reader_module
+#   Stan Smith 2014-06-05 capture an test json version
+#	Stan Smith 2014-04-23 add json schema version to internal object
+# 	Stan Smith 2013-08-23 split out metadata to module_metadata
+# 	Stan Smith 2013-08-19 split out contacts to module_contacts
+# 	Stan Smith 2013-08-09 original script
 
 require 'json'
 require_relative 'mdJson_validator'
+require_relative 'version'
+require_relative 'modules/module_mdJson'
 
 module ADIWG
     module Mdtranslator
         module Readers
             module MdJson
 
-                def self.readFile(file, responseObj)
+                def self.readFile(file, hResponseObj)
 
-                    # set reference to responseObj for use throughout this module
-                    @responseObj = responseObj
-
-                    # receive json file into ruby hash
-                    parseJson(file)
-                    if !@responseObj[:readerStructurePass]
-                        return false
-                    end
-
-                    # set format of file in $response
-                    @responseObj[:readerFormat] = 'json'
-
-                    # check mdJson version name
-                    checkVersionName
-                    if !@responseObj[:readerStructurePass]
-                        return false
-                    end
-
-                    # check mdJson version number
-                    checkVersionNumber
-                    if !@responseObj[:readerStructurePass]
-                        return false
-                    end
-
-                    # validate file against mdJson schema definition
-                    validate(file, @responseObj)
-                    if !@responseObj[:readerValidationPass]
-                        return false
-                    end
-
-                    # load mdJson file into internal object
-                    require readerModule('module_mdJson')
-                    # instance classes needed in script
-                    intMetadataClass = InternalMetadata.new
-
-                    # create new internal metadata container for the reader
-                    @intObj = intMetadataClass.newBase
-
-                    #
-                    ADIWG::Mdtranslator::Readers::MdJson.unpack(@intObj, @hMdJson, @responseObj)
-                    return @intObj
-
-                end
-
-                def self.parseJson(file)
-                    # validate the input file structure
-                    # test for valid json syntax by attempting to parse the file
+                    # parse mdJson file
                     begin
-                        @hMdJson = JSON.parse(file)
-                        @responseObj[:readerStructurePass] = true
+                        hMdJson = JSON.parse(file)
                     rescue JSON::JSONError => err
-                        @responseObj[:readerStructurePass] = false
-                        @responseObj[:readerStructureMessages] << 'JSON Parsing Failed - see following message(s):\n'
-                        @responseObj[:readerStructureMessages] << err.to_s.slice(0,300)
+                        hResponseObj[:readerStructureMessages] << 'Parsing mdJson Failed - see following message(s):\n'
+                        hResponseObj[:readerStructureMessages] << err.to_s.slice(0,300)
+                        hResponseObj[:readerStructurePass] = false
+                        return {}
                     end
-                end
 
-                def self.checkVersionName
-                    # find version name on the input json file
-                    if @hMdJson.has_key?('version')
-                        hVersion = @hMdJson['version']
-                    else
-                        @responseObj[:readerStructurePass] = false
-                        @responseObj[:readerStructureMessages] << 'Invalid input file schema declaration - see following message(s):\n'
-                        @responseObj[:readerStructureMessages] << 'The input file is missing the version:{} block.'
-                        return
+                    # file must contain an mdJson object
+                    if hMdJson.empty?
+                        hResponseObj[:readerStructureMessages] << 'mdJson object is empty'
+                        hResponseObj[:readerStructurePass] = false
+                        return {}
                     end
 
-                    # check the version name
-                    if hVersion.has_key?('name')
-                        s = hVersion['name']
-                        if s.nil?
-                            @responseObj[:readerStructurePass] = false
-                            @responseObj[:readerStructureMessages] << 'Invalid input file schema declaration - see following message(s):\n'
-                            @responseObj[:readerStructureMessages] << 'The input file version: => name: is missing.'
-                            return
-                        end
-                    else
-                        @responseObj[:readerStructurePass] = false
-                        @responseObj[:readerStructureMessages] << 'Invalid input file schema declaration - see following message(s):\n'
-                        @responseObj[:readerStructureMessages] << "The input file version:{} block is missing the 'name:' attribute."
-                        return
+                    # schema - (required)
+                    unless hMdJson.has_key?('schema')
+                        hResponseObj[:readerStructureMessages] << 'mdJson is missing schema object'
+                        hResponseObj[:readerStructurePass] = false
+                        return {}
                     end
 
-                    # check the version name is 'mdJson'
-                    if s != 'mdJson'
-                        @responseObj[:readerStructurePass] = false
-                        @responseObj[:readerStructureMessages] << 'Invalid input file schema declaration - see following message(s):\n'
-                        @responseObj[:readerStructureMessages] << "The mdTranslator reader expected the input file version: name: to be 'mdJson'."
-                        @responseObj[:readerStructureMessages] << "Version name found was: '#{s}'."
+                    # schema - name (required) (must = 'mdJson')
+                    unless hMdJson['schema'].has_key?('name')
+                        hResponseObj[:readerStructureMessages] << 'mdJson schema:name attribute is missing'
+                        hResponseObj[:readerStructurePass] = false
+                        return {}
                     end
-                end
-
-                def self.checkVersionNumber
-                    # find version number on the input json file
-                    hVersion = @hMdJson['version']
-                    if hVersion.has_key?('version')
-                        s = hVersion['version']
-                        if !s.nil?
-                            @responseObj[:readerVersionRequested] = s
-                        end
-                    else
-                        @responseObj[:readerStructurePass] = false
-                        @responseObj[:readerStructureMessages] << 'Invalid input file schema declaration - see following message(s):\n'
-                        @responseObj[:readerStructureMessages] << "The input file version:{} block is missing the 'version:' number attribute."
-                        return
+                    schemaName = hMdJson['schema']['name']
+                    if schemaName.nil? || schemaName == ''
+                        hResponseObj[:readerStructureMessages] << 'mdJson schema name is missing'
+                        hResponseObj[:readerStructurePass] = false
+                        return {}
                     end
-
-                    # split the version number into its parts
-                    aReqVersion = s.split('.')
-
-                    reqMajor = 0
-                    if !aReqVersion[0].nil?
-                        reqMajor = aReqVersion[0]
+                    unless schemaName.downcase == 'mdjson'
+                        hResponseObj[:readerStructureMessages] << "mdJson schema name is '#{schemaName}', should be mdJson"
+                        hResponseObj[:readerStructurePass] = false
+                        return {}
                     end
 
-                    # test if the requested reader major version is supported
-                    # look for a folder with modules for the major version number
-                    dirName = File.join(File.dirname(__FILE__), 'modules_v' + reqMajor)
-                    if !File.directory?(dirName)
-                        @responseObj[:readerStructurePass] = false
-                        @responseObj[:readerStructureMessages] << 'Invalid input file schema declaration - see following message(s):\n'
-                        @responseObj[:readerStructureMessages] << 'A reader for the requested version is not supported.'
-                        @responseObj[:readerStructureMessages] << "mdJson version requested was '#{s}'"
-                        return false
+                    # schema - version (required)
+                    unless hMdJson['schema'].has_key?('version')
+                        hResponseObj[:readerStructureMessages] << 'mdJson schema:version attribute is missing'
+                        hResponseObj[:readerStructurePass] = false
+                        return {}
                     end
-
-                    # the requested major version is supported
-                    # get the full version number for this major version of mdJson
-                    require File.join(dirName, 'version')
-                    curVersion = ADIWG::Mdtranslator::Readers::MdJson::VERSION
-                    @responseObj[:readerVersionUsed] = curVersion
-                    aCurVersion = curVersion.split('.')
-                    curMinor = aCurVersion[1]
-
-                    # test that minor version number is not exceeded
-                    reqMinor = 0
-                    if !aReqVersion[1].nil?
-                        reqMinor = aReqVersion[1]
-                        if curMinor < reqMinor
-                            @responseObj[:readerStructurePass] = false
-                            @responseObj[:readerStructureMessages] << 'Invalid input file schema declaration - see following message(s):\n'
-                            @responseObj[:readerStructureMessages] << 'The requested reader minor version is not supported.'
-                            @responseObj[:readerStructureMessages] << "mdJson version requested was '#{s}'"
-                            return false
-                        end
+                    requestedVersion = hMdJson['schema']['version']
+                    if requestedVersion.nil? || requestedVersion == ''
+                        hResponseObj[:readerStructureMessages] << 'mdJson schema version is missing'
+                        hResponseObj[:readerStructurePass] = false
+                        return {}
                     end
 
-                end
-
-                # find the array pointer for a contact
-                def self.findContact(contactId)
-                    pointer = nil
-                    i = 0
-                    @intObj[:contacts].each do |contact|
-                        if contact[:contactId] == contactId
-                            pointer = i
+                    # schema - 2.0.0 =< requested version =< current version
+                    currentVersion = ADIWG::Mdtranslator::Readers::MdJson::VERSION
+                    hResponseObj[:readerVersionRequested] = requestedVersion
+                    hResponseObj[:readerVersionUsed] = currentVersion
+                    aCurVersion = currentVersion.split('.')
+                    aReqVersion = requestedVersion.split('.')
+                    approved = false
+                    if aReqVersion[0] == aCurVersion[0]
+                        if aReqVersion[1] <= aCurVersion[1]
+                            approved = true
                         end
-                        i += 1
+                    end
+                    unless approved
+                        hResponseObj[:readerStructureMessages] << "mdJson schema version '#{requestedVersion}' is not supported"
+                        hResponseObj[:readerStructurePass] = false
+                        return {}
                     end
 
-                    return pointer
-                end
-
-                # require modules for the requested version
-                def self.readerModule(moduleName)
-                    majVersion = @responseObj[:readerVersionUsed].split('.')[0]
-                    dirName = File.join(File.dirname(__FILE__), 'modules_v' + majVersion.to_s)
-                    fileName = File.join(dirName, moduleName)
-
-                    # test for the existance of the module in the current mdJson version directory
-                    if !File.exist?(File.join(dirName, moduleName + '.rb'))
-                        # file not found
-                        # ... look for module in previous version directory
-                        # ... note: no previous version directories exist yet
-
-                        # no prior version directory found
-                        # ... file not found
-                        return nil
+                    # validate file against mdJson schema definition
+                    validate(hMdJson, hResponseObj)
+                    unless hResponseObj[:readerValidationPass]
+                        return {}
                     end
 
-                    return fileName
+                    # unpack the mdJson into the internal object
+                    return MdJson.unpack(hMdJson, hResponseObj)
+
                 end
 
             end

data/lib/adiwg/mdtranslator/readers/mdJson/mdJson_validator.rb

@@ -1,22 +1,20 @@
-# Get minor version of ADIwg JSON V1
+# Get minor version of ADIwg mdJson 2.x
 
 # History:
-# 	Stan Smith 2014-07-09 original script
-#   Stan Smith 2014-07-21 added json structure validation method
-#   Stan Smith 2014-08-21 parsed json-schema validation message to readable text
-#   Stan Smith 2014-09-26 added processing of minor release numbers
-#   Stan Smith 2014-12-01 changed adiwgJson to mdJson in version name check
-#   Stan Smith 2014-12-03 changed class name to MdJsonValidation from AdiwgJsonValidation
-#   Stan Smith 2014-12-11 added namespace
+#   Stan Smith 2017-02-22 refactor for mdJson/mdTranslator 2.0
 #   Stan Smith 2015-06-22 replace global ($response) with passed in object (responseObj)
+#   Stan Smith 2014-12-11 added namespace
+#   Stan Smith 2014-12-03 changed class name to MdJsonValidation from AdiwgJsonValidation
+#   Stan Smith 2014-12-01 changed adiwgJson to mdJson in version name check
+#   Stan Smith 2014-09-26 added processing of minor release numbers
+#   Stan Smith 2014-08-21 parsed json-schema validation message to readable text
+#   Stan Smith 2014-07-21 added json structure validation method
+# 	Stan Smith 2014-07-09 original script
 
 
 require 'json'
 require 'json-schema'
 require 'adiwg-mdjson_schemas'
-# temporary json-schema patch
-# waiting for rubygem json-schema patch
-require 'adiwg/mdtranslator/readers/mdJson/validator.rb'
 
 module ADIWG
     module Mdtranslator
@@ -24,24 +22,26 @@ module ADIWG
             module MdJson
 
                 # validate json against the adiwg-json_schemas
-                # only one schema version is supported at this time
+                # only a single schema version is supported at this time
                 def self.validate(file, responseObj)
 
+                    bStrict = false
+                    if responseObj[:readerValidationLevel] == 'strict'
+                        bStrict = true
+                    end
+                    ADIWG::MdjsonSchemas::Utils.load_schemas(false)
+
                     begin
-                        schema = ADIWG::MdjsonSchemas::Utils.schema_path
-                        aValErrs = Array.new
-                        if responseObj[:readerValidationLevel] == 'strict'
-                            aValErrs = JSON::Validator.fully_validate(schema, file, :strict => true, :errors_as_objects => true)
-                        elsif responseObj[:readerValidationLevel] == 'normal'
-                            aValErrs = JSON::Validator.fully_validate(schema, file, :errors_as_objects => true)
-                        end
+                        aErrors = []
+                        aErrors = JSON::Validator.fully_validate('schema.json', file, :strict=>bStrict)
 
-                        if aValErrs.length > 0
+                        if aErrors.length > 0
                             responseObj[:readerValidationPass] = false
                             responseObj[:readerValidationMessages] << 'mdJson schema validation Failed - see following message(s):\n'
-                            responseObj[:readerValidationMessages] << aValErrs
+                            responseObj[:readerValidationMessages] << aErrors
                             return
                         end
+
                     rescue JSON::Schema::ValidationError
                         responseObj[:readerValidationPass] = false
                         responseObj[:readerValidationMessages] << 'mdJson schema validation Failed - see following message(s):\n'
@@ -49,7 +49,6 @@ module ADIWG
                         return
                     end
 
-                    responseObj[:readerValidationPass] = true
                 end
 
             end

data/lib/adiwg/mdtranslator/readers/mdJson/modules/module_additionalDocumentation.rb

@@ -0,0 +1,77 @@
+# unpack additional documentation
+# Reader - ADIwg JSON to internal data structure
+
+# History:
+#   Stan Smith 2016-10-17 refactored for mdJson 2.0
+#   Stan Smith 2015-07-14 refactored to remove global namespace constants
+#   Stan Smith 2015-06-22 replace global ($response) with passed in object (responseObj)
+#   Stan Smith 2014-12-30 added return if empty input
+#   ... found & fixed error of method using associatedResource object instead of
+#   ... additionalDocumentation object
+#   Stan Smith 2014-12-15 refactored to handle namespacing readers and writers
+# 	Stan Smith 2014-11-06 original script
+
+require_relative 'module_citation'
+
+module ADIWG
+    module Mdtranslator
+        module Readers
+            module MdJson
+
+                module AdditionalDocumentation
+
+                    def self.unpack(hAddDoc, responseObj)
+
+                        # return nil object if input is empty
+                        if hAddDoc.empty?
+                            responseObj[:readerExecutionMessages] << 'Additional Documentation object is empty'
+                            responseObj[:readerExecutionPass] = false
+                            return nil
+                        end
+
+                        # instance classes needed in script
+                        intMetadataClass = InternalMetadata.new
+                        intAddDoc = intMetadataClass.newAdditionalDocumentation
+
+                        # additional documentation - resource type [] (required) {resourceType}
+                        if hAddDoc.has_key?('resourceType')
+                            hAddDoc['resourceType'].each do |item|
+                                unless item.empty?
+                                    hReturn = ResourceType.unpack(item, responseObj)
+                                    unless hReturn.nil?
+                                        intAddDoc[:resourceTypes] << hReturn
+                                    end
+                                end
+                            end
+                        end
+                        if intAddDoc[:resourceTypes].empty?
+                            responseObj[:readerExecutionMessages] << 'Additional Documentation is missing resourceType'
+                            responseObj[:readerExecutionPass] = false
+                            return nil
+                        end
+
+                        # additional documentation - citation [] (required)
+                        if hAddDoc.has_key?('citation')
+                            hAddDoc['citation'].each do |item|
+                                hDoc = Citation.unpack(item, responseObj)
+                                unless hDoc.nil?
+                                    intAddDoc[:citation] << hDoc
+                                end
+                            end
+                        end
+                        if intAddDoc[:citation].empty?
+                            responseObj[:readerExecutionMessages] << 'Additional Documentation is missing citation'
+                            responseObj[:readerExecutionPass] = false
+                            return nil
+                        end
+
+                        return intAddDoc
+
+                    end
+
+                end
+
+            end
+        end
+    end
+end