cocina-models 0.71.0 → 0.73.1

data/docs/description_types.md

@@ -0,0 +1,456 @@
+# Description types
+
+## Access accesscontact types
+_Path: access.accessContact_
+  * email: Email address for a contact person or institution concerning the resource.
+  * repository: Institution providing access to the resource.
+
+## Access digitallocation types
+_Path: access.digitalLocation_
+  * discovery: Online location for the purpose of discovering the resource.
+
+## Access note types
+_Path: access.note_
+  * access restriction: Restrictions on or conditions for gaining access to the resource.
+  * display label: Display label for the purl.
+  * license: License describing allowed uses of the resource.
+  * use and reproduction: Information related to allowed uses of the resource in other contexts.
+
+## Access physicallocation types
+_Path: access.physicalLocation_
+  * discovery: Location where a user may find the resource.
+  * location: Physical location of the resource, or path to the resource on a hard drive or disk.
+  * repository: The institution holding the resource.
+  * series: Archival series of the resource.
+  * shelf locator: Identifier or shelfmark indicating the location of the resource.
+
+## Adminmetadata note types
+_Path: adminMetadata.note_
+  * record information: General information about the metadata record.
+  * record origin: The source of the record, such as another record transformed to generate the current record.
+
+# Contributor types
+_Path: contributor_
+  * conference: An event focusing on a particular topic or discipline.
+  * event: A time-bound occurrence.
+  * family: A group of individuals related by blood or personal alliance.
+  * organization: An institution or other corporate or collective body.
+  * person: An individual identity.
+  * unspecified others: Designator for one or more additional contributors not named individually.
+
+## Contributor identifier types
+_Path: contributor.identifier_
+  * ORCID: Identifier from orcid.org.
+  * Wikidata: Identifier from wikidata.org.
+
+## Contributor name types
+_Path: contributor.name_
+  * alternative: Additional nonpreferred form of name.
+  * display: Preferred form of the name for display.
+  * forename: First or given name or names.
+  * inverted full name: Name given in last name, first name order.
+  * pseudonym: Name used that differs from legal or primary form of name.
+  * surname: Last or family name.
+  * transliteration: Name originally in non-Latin script presented phonetically using Latin characters.
+
+### Contributor name part types for structured value
+_Path: contributor.name.structuredValue_
+  * activity dates: The date or dates when someone was producing work.
+  * forename: First or given name or names.
+  * life dates: Birth and death dates, or dates when an entity was in existence.
+  * name: Name provided alongside additional information.
+  * ordinal: Indicator that the name is one in a series (e.g. Elizabeth I, Martin Luther King, Jr.).
+  * surname: Last or family name.
+  * term of address: Title or other signifier associated with name.
+
+### Contributor name types for grouped value (MODS legacy)
+_Path: contributor.name.groupedValue_
+  * alternative: Additional nonpreferred form of name.
+  * name: Primary form of name within group of values.
+  * pseudonym: Name used that differs from legal or primary form of name.
+
+## Contributor note types
+_Path: contributor.note_
+  * affiliation: Institution with which the contributor is associated.
+  * citation status: Indicator of whether the contributor should be included in the citation.
+  * description: Biographical information about the contributor.
+
+# Event types
+_Path: event_
+  * acquisition: The transferral of ownership of a resource to a repository.
+  * capture: A record of the resource in a fixed form at a specific time.
+  * collection: The addition of a resource to a set of other resources.
+  * copyright: The activity by which a resource may be considered subject to copyright law.
+  * copyright notice: An explicit statement that a resource is under copyright.
+  * creation: The coming into being of a resource.
+  * degree conferral: The institutional approval of a thesis or other resource leading to an academic degree.
+  * development: The creation of a print from a photographic negative or other source medium.
+  * distribution: The delivery of the resource to an external audience.
+  * generation: The creation of a resource by an automatic or natural process.
+  * manufacture: The physical assembly of a resource, often in multiple copies, for publication or other distribution.
+  * modification: A change to an existing resource.
+  * performance: The enactment of an artistic or cultural work for an audience, such as a play.
+  * presentation: The discussion of an academic or intellectual work for an audience, such as a seminar.
+  * production: The physical assembly of a resource not considered published, such as page proofs for a book.
+  * publication: The publishing or issuing of a resource.
+  * recording: The initial fixation to a medium of live audio and/or visual activity.
+  * release: Making a resource available to a broader audience.
+  * submission: The provision of a resource for review or evaluation.
+  * validity: When a resource takes effect, such as a revised train schedule.
+  * withdrawal: The removal of previous access to a resource, often due to its obsolescence.
+
+## Event date types
+_Path: event.date_
+  * acquisition: The transferral of ownership of a resource to a repository.
+  * capture: A record of the resource in a fixed form at a specific time.
+  * collection: The addition of a resource to a set of other resources.
+  * copyright: The activity by which a resource may be considered subject to copyright law.
+  * creation: The coming into being of a resource.
+  * degree conferral: The institutional approval of a thesis or other resource leading to an academic degree.
+  * developed: The creation of a print from a photographic negative or other source medium.
+  * development: The creation of a print from a photographic negative or other source medium.
+  * distribution: The delivery of the resource to an external audience.
+  * generation: The creation of a resource by an automatic or natural process.
+  * manufacture: The physical assembly of a resource, often in multiple copies, for publication or other distribution.
+  * modification: A change to an existing resource.
+  * performance: The enactment of an artistic or cultural work for an audience, such as a play.
+  * presentation: The discussion of an academic or intellectual work for an audience, such as a seminar.
+  * production: The physical assembly of a resource not considered published, such as page proofs for a book.
+  * publication: The publishing or issuing of a resource.
+  * recording: The initial fixation to a medium of live audio and/or visual activity.
+  * release: Making a resource available to a broader audience.
+  * submission: The provision of a resource for review or evaluation.
+  * validity: When a resource takes effect, such as a revised train schedule.
+  * withdrawal: The removal of previous access to a resource, often due to its obsolescence.
+
+### Event date part types for structured value
+_Path: event.date.structuredValue_
+  * start: The start date in a range.
+  * end: The end date in a range.
+
+## Event note types
+_Path: event.note_
+  * copyright statement: A formal declaration of copyright on a resource.
+  * edition
+  * frequency: How often a resource is issued, such as monthly.
+  * issuance: How the resource is issued, such as serially.
+
+# Form types
+_Path: form_
+  * carrier
+  * data format
+  * digital original
+  * extent
+  * form
+  * genre
+  * map projection
+  * map scale
+  * material
+  * media
+  * media type
+  * reformatting quality
+  * resource type
+  * technique
+  * type
+
+## Form note types
+_Path: form.note_
+  * additions
+  * arrangement
+  * binding
+  * codicology
+  * collation
+  * colophon
+  * condition
+  * decoNote
+  * decoration
+  * dimensions
+  * explicit
+  * foliation
+  * genre type
+  * hand note
+  * handNote
+  * incipit
+  * instrumentation
+  * layout
+  * material
+  * medium of performance
+  * provenance
+  * reassembly
+  * reproduction
+  * research
+  * rubric
+  * secfol
+  * second folio
+  * secondFolio
+  * unit
+  * writing
+
+## Form part types for structured value
+_Path: form.structuredValue_
+  * type
+  * subtype
+
+## Geographic form types
+_Path: geographic.form_
+  * data format
+  * media type
+  * type
+
+## Geographic subject types
+_Path: geographic.subject_
+  * bounding box coordinates
+  * coverage
+  * point coordinates
+
+### Geographic subject part types for structured value
+_Path: geographic.subject.structuredValue_
+  * east
+  * latitude
+  * longitude
+  * north
+  * south
+  * west
+
+# Identifier types
+_Path: identifier_
+  * accession number
+  * alternate case number
+  * Apis ID
+  * ARK
+  * arXiv
+  * case identifier
+  * case number
+  * document number
+  * DOI
+  * druid
+  * GTIN-14 ID
+  * Handle
+  * inventory number
+  * ISBN
+  * ISMN
+  * ISRC
+  * ISSN
+  * ISSN-L
+  * issue number
+  * LCCN
+  * local
+  * Local ID
+  * matrix number
+  * music plate
+  * music publisher
+  * OCLC
+  * PMCID
+  * PMID
+  * record id
+  * Senate Number
+  * Series
+  * SIRSI
+  * Source ID
+  * sourceID
+  * stock number
+  * Swets (Netherlands) ID
+  * UPC
+  * URI
+  * URN
+  * videorecording identifier
+  * West Mat \#
+  * Wikidata
+
+# Note types
+_Path: note_
+  * abstract
+  * access
+  * access note
+  * acquisition
+  * action
+  * additional physical form
+  * additions
+  * admin
+  * affiliation
+  * bibliographic
+  * bibliography
+  * biographical/historical
+  * biographical/historical note
+  * biography
+  * boat note
+  * citation/reference
+  * contact
+  * content
+  * content note
+  * content warning
+  * contents
+  * copyright
+  * creation/production credits
+  * date
+  * date/sequential designation
+  * description
+  * digitization
+  * duration
+  * event
+  * exhibitions
+  * funding
+  * general
+  * genre type
+  * geography
+  * host
+  * language
+  * local
+  * location
+  * medium of performance
+  * names
+  * numbering
+  * original location
+  * other relation type
+  * ownership
+  * part
+  * performer
+  * performers
+  * preferred citation
+  * provenance
+  * publications
+  * qualifications
+  * quote
+  * reassembly
+  * reference
+  * references
+  * related publication
+  * reproduction
+  * research
+  * restriction
+  * scope and content
+  * source characteristics
+  * source identifier
+  * statement of responsibility
+  * summary
+  * system details
+  * system requirements
+  * table of contents
+  * target audience
+  * technical note
+  * thesis
+  * transcript
+  * translation
+  * update
+  * use and reproduction
+  * venue
+  * version
+  * version identification
+  * writing
+
+## Note types for grouped value (MODS legacy)
+_Path: note.groupedValue_
+  * caption
+  * date
+  * detail type
+  * extent unit
+  * list
+  * marker
+  * number
+  * title
+  * text
+
+# Relatedresource types
+_Path: relatedResource_
+  * has original version: An initial form of the resource.
+  * has other format: A version of the resource in a different physical or digital format.
+  * has part: A constituent unit of the resource.
+  * has version: A version of the resource with different intellectual content.
+  * in series: The name of a series of publications to which the resource belongs.
+  * other relation type: Resource type not otherwise described.
+  * part of: A larger resource to which the resource belongs, such as a collection.
+  * preceded by: A predecessor to the resource, such as a preceding journal title.
+  * referenced by: Other resources that cite the resource, such as a catalog.
+  * references: A resource which the resource references or cites.
+  * related to: A generically related resource.
+  * reviewed by: A review of the resource.
+  * succeeded by: A successor to the resource, such as a subsequent journal title.
+
+# Subject types
+_Path: subject_
+  * classification
+  * conference
+  * display
+  * event
+  * family
+  * genre
+  * map coordinates
+  * name
+  * occupation
+  * organization
+  * person
+  * place
+  * point coordinates
+  * time
+  * title
+  * topic
+
+## Subject note types
+_Path: subject.note_
+  * role
+
+## Subject part types for structured value
+_Path: subject.structuredValue_
+  * activity dates
+  * city
+  * conference
+  * continent
+  * country
+  * end
+  * east
+  * event
+  * display
+  * family
+  * forename
+  * genre
+  * latitude
+  * life dates
+  * longitude
+  * main title
+  * name
+  * north
+  * occupation
+  * ordinal
+  * organization
+  * part name
+  * person
+  * place
+  * south
+  * start
+  * surname
+  * term of address
+  * time
+  * title
+  * topic
+  * west
+
+### Subject note types
+_Path: subject.structuredValue.note_
+  * role: The relation of the subject entity to the resource.
+
+## Subject types for grouped value (MODS legacy)
+_Path: subject.groupedValue_
+  * uniform: Form of title in Library of Congress title authority.
+
+# Title types
+_Path: title_
+  * abbreviated: Abbreviated form of title for indexing or identification.
+  * alternative: Variant title.
+  * parallel: Title transcribed from the resource in multiple languages or scripts.
+  * supplied: Title provided by metadata creator rather than transcribed from the resource.
+  * translated: Title translated into another language.
+  * transliterated: Title transliterated from non-Latin script to Latin script.
+  * uniform: Form of title in Library of Congress title authority.
+
+## Title note types
+_Path: title.note_
+  * associated name: A name linked to the title, such as for a name-title heading.
+  * nonsorting character count: The number of characters at the beginning of the string to be disregarded when sorting.
+
+## Title part types for structured value
+_Path: title.structuredValue_
+  * main title: The primary part of a multipart title.
+  * nonsorting characters: A string at the beginning of the title to be disregarded when sorting.
+  * part name: The distinct name of a resource as part of a series or multivolume set.
+  * part number: The distinct number of a resource as part of a series or multivolume set.
+  * subtitle: The secondary part of a title.

data/lib/cocina/generator/generator.rb

@@ -28,6 +28,7 @@ module Cocina
         # rubocop:enable Style/HashEachMethods
 
         generate_vocab
+        generate_descriptive_docs
       end
 
       desc 'generate_schema SCHEMA_NAME', 'generate for SCHEMA_NAME'
@@ -45,8 +46,56 @@ module Cocina
         Vocab.generate(schemas, output_dir: options[:output])
       end
 
+      desc 'generate_descriptive_docs', 'generate descriptive documentation'
+      def generate_descriptive_docs
+        markdown = YAML.load_file('description_types.yml').map do |field, types|
+          header_markdown = field_markdown_from(field)
+          types_markdown = types_markdown_from(types)
+
+          <<~MARKDOWN
+            #{'#' * (field.count('.') + 1)} #{header_markdown}
+            _Path: #{field}_
+            #{types_markdown}
+          MARKDOWN
+        end.join("\n")
+
+        remove_file 'docs/description_types.md'
+        create_file 'docs/description_types.md', h1_markdown + markdown
+      end
+
       private
 
+      def h1_markdown
+        <<~MARKDOWN
+          # Description types
+
+        MARKDOWN
+      end
+
+      def field_markdown_from(field)
+        header = field.split('.')
+                      .grep_v(/groupedValue|structuredValue/)
+                      .join(' ')
+                      .capitalize
+
+        header_suffix = if field.ends_with?('structuredValue')
+                          'part types for structured value'
+                        elsif field.ends_with?('groupedValue')
+                          'types for grouped value (MODS legacy)'
+                        else
+                          'types'
+                        end
+        "#{header} #{header_suffix}"
+      end
+
+      def types_markdown_from(types)
+        types.map do |type|
+          "  * #{type['value']}".tap do |type_value|
+            type_value << ": #{type['description']}" if type['description']
+          end
+        end.join("\n")
+      end
+
       def schemas
         @schemas ||= Openapi3Parser.load_file(options[:openapi]).components.schemas
       end
@@ -78,7 +127,6 @@ module Cocina
         'rights_description_builder.rb',
         'title_builder.rb',
         'validatable.rb',
-        'validator.rb',
         'version.rb',
         'vocabulary.rb'
       ].freeze

data/lib/cocina/models/access_role.rb

@@ -4,7 +4,7 @@ module Cocina
   module Models
     class AccessRole < Struct
       # Name of role
-      attribute :name, Types::Strict::String.enum('dor-apo-creator', 'dor-apo-depositor', 'dor-apo-manager', 'dor-apo-metadata', 'dor-apo-reviewer', 'dor-apo-viewer', 'sdr-administrator', 'sdr-viewer', 'hydrus-collection-creator', 'hydrus-collection-manager', 'hydrus-collection-depositor', 'hydrus-collection-item-depositor', 'hydrus-collection-reviewer', 'hydrus-collection-viewer')
+      attribute :name, Types::Strict::String.enum('dor-apo-depositor', 'dor-apo-manager', 'dor-apo-viewer', 'sdr-administrator', 'sdr-viewer', 'hydrus-collection-creator', 'hydrus-collection-manager', 'hydrus-collection-depositor', 'hydrus-collection-item-depositor', 'hydrus-collection-reviewer', 'hydrus-collection-viewer')
       attribute :members, Types::Strict::Array.of(AccessRoleMember).default([].freeze)
     end
   end

data/lib/cocina/models/catalog_link.rb

@@ -5,7 +5,9 @@ module Cocina
     class CatalogLink < Struct
       # Catalog that is the source of the linked record.
       # example: symphony
-      attribute :catalog, Types::Strict::String
+      attribute :catalog, Types::Strict::String.enum('symphony', 'previous symphony')
+      # Only one of the catkeys should be designated for refreshing. This means that this key is the one used to pull metadata from the catalog if there is more than one key present.
+      attribute :refresh, Types::Strict::Bool.default(false)
       # Record identifier that is unique within the context of the linked record's catalog.
       # example: 11403803
       attribute :catalogRecordId, Types::Strict::String

data/lib/cocina/models/title_builder.rb

@@ -46,8 +46,7 @@ module Cocina
         result = if cocina_title.value
                    cocina_title.value
                  elsif cocina_title.structuredValue.present?
-                   title_from_structured_values(cocina_title.structuredValue,
-                                                non_sorting_char_count(cocina_title))
+                   title_from_structured_values(cocina_title)
                  elsif cocina_title.parallelValue.present?
                    return build(cocina_title.parallelValue)
                  end
@@ -104,20 +103,17 @@ module Cocina
       # rubocop:disable Metrics/PerceivedComplexity
       # rubocop:disable Metrics/MethodLength
       # rubocop:disable Metrics/AbcSize
-      # @param [Array<Cocina::Models::StructuredValue>] structured_values - the pieces of a structuredValue
-      # @param [Integer] the length of the non_sorting_characters
+      # @param [Cocina::Models::Title] title with structured values
       # @return [String] the title value from combining the pieces of the structured_values by type and order
       #   with desired punctuation per specs
-      def title_from_structured_values(structured_values, non_sorting_char_count)
+      def title_from_structured_values(title)
         structured_title = ''
         part_name_number = ''
         # combine pieces of the cocina structuredValue into a single title
-        structured_values.each do |structured_value|
+        title.structuredValue.each do |structured_value|
           # There can be a structuredValue inside a structuredValue.  For example,
           #   a uniform title where both the name and the title have internal StructuredValue
-          if structured_value.structuredValue.present?
-            return title_from_structured_values(structured_value.structuredValue, non_sorting_char_count)
-          end
+          return title_from_structured_values(structured_value) if structured_value.structuredValue.present?
 
           value = structured_value.value&.strip
           next unless value
@@ -125,8 +121,7 @@ module Cocina
           # additional types:  name, uniform ...
           case structured_value.type&.downcase
           when 'nonsorting characters'
-            non_sorting_size = [non_sorting_char_count - (value&.size || 0), 0].max
-            non_sort_value = "#{value}#{' ' * non_sorting_size}"
+            non_sort_value = "#{value}#{non_sorting_padding(title, value)}"
             structured_title = if structured_title.present?
                                  "#{structured_title}#{non_sort_value}"
                                else
@@ -134,7 +129,7 @@ module Cocina
                                end
           when 'part name', 'part number'
             if part_name_number.blank?
-              part_name_number = part_name_number(structured_values)
+              part_name_number = part_name_number(title.structuredValue)
               structured_title = if !add_punctuation?
                                    [structured_title, part_name_number].join(' ')
                                  elsif structured_title.present?
@@ -168,11 +163,16 @@ module Cocina
         title.sub(%r{[ .,;:/\\]+$}, '')
       end
 
-      def non_sorting_char_count(title)
+      def non_sorting_padding(title, non_sorting_value)
         non_sort_note = title.note&.find { |note| note.type&.downcase == 'nonsorting character count' }
-        return 0 unless non_sort_note
-
-        non_sort_note.value.to_i
+        if non_sort_note
+          padding_count = [non_sort_note.value.to_i - non_sorting_value.length, 0].max
+          ' ' * padding_count
+        elsif ['\'', '-'].include?(non_sorting_value.last)
+          ''
+        else
+          ' '
+        end
       end
 
       # combine part name and part number:

data/lib/cocina/models/validatable.rb

@@ -8,7 +8,7 @@ module Cocina
 
       class_methods do
         def new(attributes = default_attributes, safe = false, validate = true, &block)
-          Validator.validate(self, attributes.with_indifferent_access) if validate && name
+          Validators::Validator.validate(self, attributes.with_indifferent_access) if validate
           super(attributes, safe, &block)
         end
       end
@@ -16,7 +16,7 @@ module Cocina
       def new(*args)
         validate = args.first.delete(:validate) if args.present?
         new_model = super(*args)
-        Validator.validate(new_model.class, new_model.to_h) if (validate || validate.nil?) && self.class.name
+        Validators::Validator.validate(new_model.class, new_model.to_h) if validate || validate.nil?
         new_model
       end
     end

data/lib/cocina/models/validators/catalog_links_validator.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Cocina
+  module Models
+    module Validators
+      # Validates that only a single CatalogLink has refresh set to true
+      class CatalogLinksValidator
+        MAX_REFRESH_CATALOG_LINKS = 1
+
+        def self.validate(clazz, attributes)
+          new(clazz, attributes).validate
+        end
+
+        def initialize(clazz, attributes)
+          @clazz = clazz
+          @attributes = attributes
+        end
+
+        def validate
+          return unless meets_preconditions?
+
+          return if refresh_catalog_links.length <= MAX_REFRESH_CATALOG_LINKS
+
+          raise ValidationError, "Multiple catalog links have 'refresh' property set to true " \
+                                 "(only one allowed) #{refresh_catalog_links}"
+        end
+
+        private
+
+        attr_reader :clazz, :attributes
+
+        def meets_preconditions?
+          (dro? || collection?) && Array(attributes.dig(:identification, :catalogLinks)).any?
+        end
+
+        def refresh_catalog_links
+          attributes.dig(:identification, :catalogLinks).select { |catalog_link| catalog_link[:refresh] }
+        end
+
+        def dro?
+          (clazz::TYPES & DRO::TYPES).any?
+        rescue NameError
+          false
+        end
+
+        def collection?
+          (clazz::TYPES & Collection::TYPES).any?
+        rescue NameError
+          false
+        end
+      end
+    end
+  end
+end