cocina-models 0.69.2 → 0.72.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 191508cff01be391223c83aba3e7c085e99b581a0f12a95dcd627572fbe5be36
-  data.tar.gz: b4eb3927706c3a5316f30d03d0352e742b3b0a72bf966cb9b0ed6bb593a0d48d
+  metadata.gz: b5516cbeff2267e688f6a09b34e4a0c715a1aea91ddae03d10060bed3d364c5a
+  data.tar.gz: f47bd2a4ca35c95d3566883707d39a2480c0b7e18ee28bc49042aa90b24e104c
 SHA512:
-  metadata.gz: 8a4e9c462003e94e13992d20e2adc1a88515185820c11f851b0e709913addb541efadb35d11a0c841cb563e26d0b98cea15b0c0cc9d14aeddeb93f5bc953b147
-  data.tar.gz: 501f90b85f9386ff832b4147483d6e46fd6e8735fe87de6b868e7f68e2c6a02f1cf71759cb649103bcff93fb9e5830c11cd3ac0387e85336821237f8add0ee71
+  metadata.gz: 262cdfa4049c7325751645a578b2129f0f5cc4737198b82bea5728a6d693398bf2ab589dea2ae912de2de09e6abd1e3a581b84828f3ebf85ed64ba4c3a71dc25
+  data.tar.gz: 977677a8f5de44340117f3d2fb6ba8553e21c3c61c1770b18d44652008de6e26a6ada747de9546e993a0e4231e2263ad531d97491c5467d8aa8e18f2a303f340

data/.rubocop.yml

@@ -107,7 +107,7 @@ RSpec/StubbedMock: # (new in 1.44)
   Enabled: true
 
 RSpec/MultipleMemoizedHelpers:
-  Max: 6
+  Enabled: false
 
 # ----- Style ------
 

data/README.md

@@ -53,10 +53,14 @@ which pushes the gem to rubygems.org.  Next write up the release notes: https://
 
 ### Step 2: Update client gems coupled to the models
 
+**NOTE**: You can skip this step if the new release is a patch-level bump only.
+
 Next, you should release versions of [sdr-client](https://github.com/sul-dlss/sdr-client) and [dor-services-client](https://github.com/sul-dlss/dor-services-client/) pinned to this version because applications such as [Argo](https://github.com/sul-dlss/argo) depend on both of these gems using the same models.
 
 ### Step 3: Update service API specifications and gems
 
+**NOTE**: You can skip this first half of the step if there have not been any changes to the `cocina-models` OpenAPI spec since the prior release.
+
 The cocina-models gem is used in applications that have an API specification that accepts Cocina models. Next, make sure that the `openapi.yml` for these applications include the `openapi.yml` schema changes made in cocina-models. This list of services is known to include:
 
 * [sul-dlss/sdr-api](https://github.com/sul-dlss/sdr-api)
@@ -85,7 +89,9 @@ There are scripts to help with this:
 
 #### Step 4A: Create the PRs
 
-access-update-scripts repo has a script for this:  `cocina_level2_prs.rb`.  You will need a github access token with scopes of "read:org" and "repo" (see https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) to run it, as noted in the comments at the top of that script.
+There is a Jenkins CI job that you can run manually to create all the PRs you need. Head to https://sul-ci-prod.stanford.edu/job/SUL-DLSS/job/access-update-scripts/job/cocina-level2-updates/ and then click `Build Now`. Click the new build that is created and then `Console Output` to watch the build. Once it has completed, you can proceed with the next step.
+
+If for some reason the above method does not work, the sul-dlss/access-update-scripts repo has a script for this: `cocina_level2_prs.rb`. You will need a github access token with scopes of "read:org" and "repo" (see https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) to run it, as noted in the comments at the top of that script.
 
 #### Step 4B: Merge the PRs
 
@@ -95,11 +101,24 @@ access-update-scripts repo has a script for this:  `cocina_level2_prs.rb`.  You
 
 [sul-dlss/sdr-deploy](https://github.com/sul-dlss/sdr-deploy) has a flag in the deploy script to limit deploys to cocina dependent applications.  Refer to instructions in the [sdr-deploy/README](https://github.com/sul-dlss/sdr-deploy/blob/main/README.md#only-deploy-repos-related-to-cocina-models-update).
 
+Note that running the integration tests is currently the best way we have to check for unintended effects and/or bugs when rolling out cocina-models changes.
+
+#### Step 5A: Deploy to QA and/or Stage
+
+#### Step 5B: Run infrastructure_integration_tests
+
+It is safest to ensure _all_ the integration tests run cleanly.  However, patch releases of cocina-models may only warrant running individual tests that exercise the changes.
+
+#### Step 5C: Deploy to Production
+
+**[Turn off Google Books](https://sul-gbooks-prod.stanford.edu/features) when deploying to production.** This avoids failed deposit due to a temporary Cocina model mismatch. Unlike other applications, the deposits will fail without retry and require manual remediation.
+
 ## Usage conventions
 
 The following are the recommended naming conventions for code using Cocina models:
 
 * `cocina_item`: `Cocina::Models::DRO` instance
+* `cocina_agreement`: `Cocina::Models::DRO` with type of Cocina::Models::ObjectType.agreement
 * `cocina_admin_policy`: `Cocina::Models::AdminPolicy` instance
 * `cocina_collection`: `Cocina::Models::Collection` instance
 * `cocina_object`: `Cocina::Models::DRO` or `Cocina::Models::AdminPolicy` or `Cocina::Models::Collection` instance
@@ -112,7 +131,7 @@ As of the 0.69.0 release, the `cocina-models` gem provides RSpec matchers for do
   * `expect(http_response_body_with_cocina_json).to equal_cocina_model(cocina_instance)`
 * `cocina_object_with` (AKA `match_cocina_object_with`): Compare a Cocina model instance with a hash containining part of the structure of a Cocina object. Example usage:
   * `expect(CocinaObjectStore).to have_received(:save).with(cocina_object_with(access: { view: 'world' }, structural: { contains: [...] }))`
-  * expect(updated_cocina_item).to match_cocina_object_with(structural: { hasMemberOrders: [] })
+  * `expect(updated_cocina_item).to match_cocina_object_with(structural: { hasMemberOrders: [] })`
 * `cocina_object_with_types`: Check a Cocina object's type information. Example usage:
   * `expect(object_client).to have_received(:update).with(params: cocina_object_with_types(content_type: Cocina::Models::ObjectType.book, viewing_direction: 'left-to-right'))`
 * `cocina_admin_policy_with_registration_collections`: Check a Cocina admin policy's collections. Example usage:

data/cocina-models.gemspec

@@ -25,6 +25,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 2.7'
 
   spec.add_dependency 'activesupport'
+  spec.add_dependency 'deprecation'
   spec.add_dependency 'dry-struct', '~> 1.0'
   spec.add_dependency 'dry-types', '~> 1.1'
   spec.add_dependency 'openapi3_parser' # Parsing openapi doc

data/lib/cocina/generator/generator.rb

@@ -78,7 +78,6 @@ module Cocina
         'rights_description_builder.rb',
         'title_builder.rb',
         'validatable.rb',
-        'validator.rb',
         'version.rb',
         'vocabulary.rb'
       ].freeze

data/lib/cocina/generator/schema.rb

@@ -47,10 +47,13 @@ module Cocina
       end
 
       def types
-        type_properties_doc = schema_doc.properties['type']
-        return '' if type_properties_doc.nil? || type_properties_doc.enum.nil?
+        type_schema_property = schema_properties.find { |schema_property| schema_property.key == 'type' }
+        return '' if type_schema_property.nil?
 
-        types_list = type_properties_doc.enum.map { |item| "'#{item}'" }.join(",\n ")
+        type_schema_doc = type_schema_property.schema_doc
+        return '' if type_schema_doc.enum.nil?
+
+        types_list = type_schema_doc.enum.map { |item| "'#{item}'" }.join(",\n ")
 
         <<~RUBY
           include Checkable

data/lib/cocina/models/admin_policy_with_metadata.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Cocina
+  module Models
+    class AdminPolicyWithMetadata < Struct
+      include Validatable
+
+      include Checkable
+
+      TYPES = ['https://cocina.sul.stanford.edu/models/admin_policy'].freeze
+
+      # The version of Cocina with which this object conforms.
+      # example: 1.2.3
+      attribute :cocinaVersion, Types::Strict::String.default(Cocina::Models::VERSION)
+      attribute :type, Types::Strict::String.enum(*AdminPolicyWithMetadata::TYPES)
+      # example: druid:bc123df4567
+      attribute :externalIdentifier, Types::Strict::String
+      attribute :label, Types::Strict::String
+      attribute :version, Types::Strict::Integer
+      attribute(:administrative, AdminPolicyAdministrative.default { AdminPolicyAdministrative.new })
+      attribute :description, Description.optional.meta(omittable: true)
+      # When the object was created.
+      attribute :created, Types::Params::DateTime.meta(omittable: true)
+      # When the object was modified.
+      attribute :modified, Types::Params::DateTime.meta(omittable: true)
+      # Key for optimistic locking. The contents of the key is not specified.
+      attribute :lock, Types::Strict::String
+    end
+  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/collection.rb

@@ -25,9 +25,9 @@ module Cocina
       # Version for the Collection within SDR.
       attribute :version, Types::Strict::Integer
       attribute(:access, CollectionAccess.default { CollectionAccess.new })
-      attribute :administrative, Administrative.optional.meta(omittable: true)
+      attribute(:administrative, Administrative.default { Administrative.new })
       attribute(:description, Description.default { Description.new })
-      attribute :identification, CollectionIdentification.optional.meta(omittable: true)
+      attribute(:identification, CollectionIdentification.default { CollectionIdentification.new })
     end
   end
 end

data/lib/cocina/models/collection_with_metadata.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Cocina
+  module Models
+    class CollectionWithMetadata < Struct
+      include Validatable
+
+      include Checkable
+
+      TYPES = ['https://cocina.sul.stanford.edu/models/collection',
+               'https://cocina.sul.stanford.edu/models/curated-collection',
+               'https://cocina.sul.stanford.edu/models/user-collection',
+               'https://cocina.sul.stanford.edu/models/exhibit',
+               'https://cocina.sul.stanford.edu/models/series'].freeze
+
+      # The version of Cocina with which this object conforms.
+      # example: 1.2.3
+      attribute :cocinaVersion, Types::Strict::String.default(Cocina::Models::VERSION)
+      # The content type of the Collection. Selected from an established set of values.
+      attribute :type, Types::Strict::String.enum(*CollectionWithMetadata::TYPES)
+      # example: druid:bc123df4567
+      attribute :externalIdentifier, Types::Strict::String
+      # Primary processing label (can be same as title) for a Collection.
+      attribute :label, Types::Strict::String
+      # Version for the Collection within SDR.
+      attribute :version, Types::Strict::Integer
+      attribute(:access, CollectionAccess.default { CollectionAccess.new })
+      attribute(:administrative, Administrative.default { Administrative.new })
+      attribute(:description, Description.default { Description.new })
+      attribute(:identification, CollectionIdentification.default { CollectionIdentification.new })
+      # When the object was created.
+      attribute :created, Types::Params::DateTime.meta(omittable: true)
+      # When the object was modified.
+      attribute :modified, Types::Params::DateTime.meta(omittable: true)
+      # Key for optimistic locking. The contents of the key is not specified.
+      attribute :lock, Types::Strict::String
+    end
+  end
+end

data/lib/cocina/models/dro.rb

@@ -37,8 +37,8 @@ module Cocina
       attribute(:access, DROAccess.default { DROAccess.new })
       attribute(:administrative, Administrative.default { Administrative.new })
       attribute(:description, Description.default { Description.new })
-      attribute :identification, Identification.optional.meta(omittable: true)
-      attribute :structural, DROStructural.optional.meta(omittable: true)
+      attribute(:identification, Identification.default { Identification.new })
+      attribute(:structural, DROStructural.default { DROStructural.new })
       attribute :geographic, Geographic.optional.meta(omittable: true)
     end
   end

data/lib/cocina/models/dro_with_metadata.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Cocina
+  module Models
+    class DROWithMetadata < Struct
+      include Validatable
+
+      include Checkable
+
+      TYPES = ['https://cocina.sul.stanford.edu/models/object',
+               'https://cocina.sul.stanford.edu/models/3d',
+               'https://cocina.sul.stanford.edu/models/agreement',
+               'https://cocina.sul.stanford.edu/models/book',
+               'https://cocina.sul.stanford.edu/models/document',
+               'https://cocina.sul.stanford.edu/models/geo',
+               'https://cocina.sul.stanford.edu/models/image',
+               'https://cocina.sul.stanford.edu/models/page',
+               'https://cocina.sul.stanford.edu/models/photograph',
+               'https://cocina.sul.stanford.edu/models/manuscript',
+               'https://cocina.sul.stanford.edu/models/map',
+               'https://cocina.sul.stanford.edu/models/media',
+               'https://cocina.sul.stanford.edu/models/track',
+               'https://cocina.sul.stanford.edu/models/webarchive-binary',
+               'https://cocina.sul.stanford.edu/models/webarchive-seed'].freeze
+
+      # The version of Cocina with which this object conforms.
+      # example: 1.2.3
+      attribute :cocinaVersion, Types::Strict::String.default(Cocina::Models::VERSION)
+      # The content type of the DRO. Selected from an established set of values.
+      attribute :type, Types::Strict::String.enum(*DROWithMetadata::TYPES)
+      # example: druid:bc123df4567
+      attribute :externalIdentifier, Types::Strict::String
+      # Primary processing label (can be same as title) for a DRO.
+      attribute :label, Types::Strict::String
+      # Version for the DRO within SDR.
+      attribute :version, Types::Strict::Integer
+      attribute(:access, DROAccess.default { DROAccess.new })
+      attribute(:administrative, Administrative.default { Administrative.new })
+      attribute(:description, Description.default { Description.new })
+      attribute(:identification, Identification.default { Identification.new })
+      attribute(:structural, DROStructural.default { DROStructural.new })
+      attribute :geographic, Geographic.optional.meta(omittable: true)
+      # When the object was created.
+      attribute :created, Types::Params::DateTime.meta(omittable: true)
+      # When the object was modified.
+      attribute :modified, Types::Params::DateTime.meta(omittable: true)
+      # Key for optimistic locking. The contents of the key is not specified.
+      attribute :lock, Types::Strict::String
+    end
+  end
+end

data/lib/cocina/models/file_set.rb

@@ -29,7 +29,7 @@ module Cocina
       attribute :label, Types::Strict::String
       # Version for the Fileset within SDR.
       attribute :version, Types::Strict::Integer
-      attribute :structural, FileSetStructural.optional.meta(omittable: true)
+      attribute(:structural, FileSetStructural.default { FileSetStructural.new })
     end
   end
 end

data/lib/cocina/models/identification.rb

@@ -12,7 +12,7 @@ module Cocina
       # Unique identifier in some other system. This is because a large proportion of what is deposited in SDR, historically and currently, are representations of objects that are also represented in other systems. For example, digitized paper and A/V collections have physical manifestations, and those physical objects are managed in systems that have their own identifiers. Similarly, books have barcodes, archival materials have collection numbers and physical locations, etc. The sourceId allows determining if an item has been deposited before and where to look for the original item if you're looking at its SDR representation. The format is: "namespace:identifier"
 
       # example: sul:PC0170_s3_Fiesta_Bowl_2012-01-02_210609_2026
-      attribute :sourceId, Types::Strict::String.meta(omittable: true)
+      attribute :sourceId, Types::Strict::String
     end
   end
 end

data/lib/cocina/models/object_metadata.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Cocina
+  module Models
+    class ObjectMetadata < Struct
+      # When the object was created.
+      attribute :created, Types::Params::DateTime.meta(omittable: true)
+      # When the object was modified.
+      attribute :modified, Types::Params::DateTime.meta(omittable: true)
+      # Key for optimistic locking. The contents of the key is not specified.
+      attribute :lock, Types::Strict::String
+    end
+  end
+end

data/lib/cocina/models/title_builder.rb

@@ -1,30 +1,35 @@
 # frozen_string_literal: true
 
+require 'deprecation'
+
 module Cocina
   module Models
     # TitleBuilder selects the prefered title from the cocina object for solr indexing
     # rubocop:disable Metrics/ClassLength
     class TitleBuilder
-      # @param [Cocina::Models::D*] cocina_object is the object to extract the title for
+      extend Deprecation
+      # @param [[Array<Cocina::Models::Title,Cocina::Models::DescriptiveValue>] titles the titles to consider
       # @param [Symbol] strategy ":first" is the strategy for selection when primary or display title are missing
       # @param [Boolean] add_punctuation determines if the title should be formmated with punctuation
       # @return [String] the title value for Solr
-      def self.build(cocina_object, strategy: :first, add_punctuation: true)
-        new(cocina_object, strategy: strategy, add_punctuation: add_punctuation).build_title
+      def self.build(titles, strategy: :first, add_punctuation: true)
+        if titles.respond_to?(:description)
+          Deprecation.warn(self, "Calling TitleBuilder.build with a #{titles.class} is deprecated. It must be called with an array of titles")
+          titles = titles.description.title
+        end
+        new(strategy: strategy, add_punctuation: add_punctuation).build(titles)
       end
 
-      def initialize(cocina_object, strategy:, add_punctuation:)
-        @cocina_object = cocina_object
+      def initialize(strategy:, add_punctuation:)
         @strategy = strategy
         @add_punctuation = add_punctuation
       end
 
+      # @param [[Array<Cocina::Models::Title>] titles the titles to consider
       # @return [String] the title value for Solr
-      def build_title
-        @titles = cocina_object.description.title
-
-        cocina_title = primary_title || untyped_title
-        cocina_title = other_title if cocina_title.blank?
+      def build(titles)
+        cocina_title = primary_title(titles) || untyped_title(titles)
+        cocina_title = other_title(titles) if cocina_title.blank?
 
         if strategy == :first
           extract_title(cocina_title)
@@ -35,16 +40,15 @@ module Cocina
 
       private
 
-      attr_reader :cocina_object, :strategy, :titles
+      attr_reader :strategy
 
       def extract_title(cocina_title)
         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 cocina_title.parallelValue.first.value
+                   return build(cocina_title.parallelValue)
                  end
         remove_trailing_punctuation(result.strip) if result.present?
       end
@@ -54,7 +58,7 @@ module Cocina
       end
 
       # @return [Cocina::Models::Title, nil] title that has status=primary
-      def primary_title
+      def primary_title(titles)
         primary_title = titles.find do |title|
           title.status == 'primary'
         end
@@ -69,7 +73,7 @@ module Cocina
         end
       end
 
-      def untyped_title
+      def untyped_title(titles)
         method = strategy == :first ? :find : :select
         untyped_title_for(titles.public_send(method))
       end
@@ -86,7 +90,7 @@ module Cocina
       end
 
       # This handles 'main title', 'uniform' or 'translated'
-      def other_title
+      def other_title(titles)
         if strategy == :first
           titles.first
         else
@@ -99,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
@@ -120,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
@@ -129,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?
@@ -163,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

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Cocina
+  module Models
+    module Validators
+      # Validates that shelve and publish file attributes are set to false for dark DRO objects.
+      class DarkValidator
+        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 invalid_files.empty?
+
+          raise ValidationError, 'Not all files have dark access and/or are unshelved ' \
+                                 "when object access is dark: #{invalid_filenames}"
+        end
+
+        private
+
+        attr_reader :clazz, :attributes
+
+        def meets_preconditions?
+          dro? && attributes.dig(:access, :view) == 'dark'
+        end
+
+        def dro?
+          (clazz::TYPES & DRO::TYPES).any?
+        rescue NameError
+          false
+        end
+
+        def invalid_files
+          @invalid_files ||=
+            [].tap do |invalid_files|
+              files.each do |file|
+                invalid_files << file if invalid?(file)
+              end
+            end
+        end
+
+        def invalid_filenames
+          invalid_files.map { |invalid_file| invalid_file[:filename] || invalid_file[:label] }
+        end
+
+        def invalid?(file)
+          # Ignore if a WARC
+          return false if file[:hasMimeType] == 'application/warc'
+
+          return true if file.dig(:administrative, :shelve)
+          return true if file.dig(:access, :view) != 'dark'
+
+          false
+        end
+
+        def files
+          [].tap do |files|
+            next if attributes.dig(:structural, :contains).nil?
+
+            attributes[:structural][:contains].each do |fileset|
+              next if fileset.dig(:structural, :contains).nil?
+
+              fileset[:structural][:contains].each do |file|
+                files << file
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Cocina
+  module Models
+    module Validators
+      # Perform validation against openapi
+      class OpenApiValidator
+        def self.validate(clazz, attributes)
+          return unless clazz.name
+
+          method_name = clazz.name.split('::').last
+          request_operation = root.request_operation(:post, "/validate/#{method_name}")
+
+          # JSON.parse forces serialization of objects like DateTime.
+          json_attributes = JSON.parse(attributes.to_json)
+          # Inject cocinaVersion if needed and not present.
+          if operation_has_cocina_version?(request_operation) && !json_attributes.include?('cocinaVersion')
+            json_attributes['cocinaVersion'] = Cocina::Models::VERSION
+          end
+
+          request_operation.validate_request_body('application/json', json_attributes)
+        rescue OpenAPIParser::OpenAPIError => e
+          raise ValidationError, e.message
+        end
+
+        # rubocop:disable Metrics/AbcSize
+        # rubocop:disable Metrics/CyclomaticComplexity
+        def self.operation_has_cocina_version?(request_operation)
+          schema = request_operation.operation_object.request_body.content['application/json'].schema
+          all_of_properties = Array(schema.all_of&.flat_map { |all_of| all_of.properties&.keys }).compact
+          one_of_properties = Array(schema.one_of&.flat_map { |one_of| one_of.properties&.keys }).compact
+          properties = Array(schema.properties&.keys)
+          (properties + all_of_properties + one_of_properties).include?('cocinaVersion')
+        end
+        # rubocop:enable Metrics/AbcSize
+        # rubocop:enable Metrics/CyclomaticComplexity
+        private_class_method :operation_has_cocina_version?
+
+        # rubocop:disable Style/ClassVars
+        def self.root
+          @@root ||= OpenAPIParser.parse(YAML.load_file(openapi_path), strict_reference_validation: true)
+        end
+        # rubocop:enable Style/ClassVars
+        private_class_method :root
+
+        def self.openapi_path
+          ::File.expand_path('../../../../openapi.yml', __dir__)
+        end
+        private_class_method :openapi_path
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Cocina
+  module Models
+    module Validators
+      # Perform validation against all other Validators
+      class Validator
+        VALIDATORS = [OpenApiValidator, DarkValidator, CatalogLinksValidator].freeze
+
+        def self.validate(clazz, attributes)
+          VALIDATORS.each { |validator| validator.validate(clazz, attributes) }
+        end
+      end
+    end
+  end
+end

data/lib/cocina/models/version.rb

@@ -2,6 +2,6 @@
 
 module Cocina
   module Models
-    VERSION = '0.69.2'
+    VERSION = '0.72.0'
   end
 end

data/lib/cocina/models/vocabulary.rb

@@ -25,6 +25,15 @@ module Cocina
       def self.properties
         @properties ||= {}
       end
+
+      ##
+      # Returns the URI for the term `property` in this vocabulary.
+      #
+      # @param  [#to_sym] property
+      # @return [String]
+      def self.[](property)
+        properties[property.to_sym]
+      end
     end
   end
 end

data/lib/cocina/models.rb

@@ -21,6 +21,7 @@ class CocinaModelsInflector < Zeitwerk::Inflector
     'request_dro' => 'RequestDRO',
     'dro_access' => 'DROAccess',
     'dro_structural' => 'DROStructural',
+    'dro_with_metadata' => 'DROWithMetadata',
     'request_dro_structural' => 'RequestDROStructural',
     'rspec' => 'RSpec',
     'version' => 'VERSION'
@@ -110,6 +111,38 @@ module Cocina
       clazz.new(dyn, false, validate)
     end
 
+    # Coerces DROWithMetadata, CollectionWithMetadata, AdminPolicyWithMetadata to DRO, Collection, AdminPolicy
+    # @param [DROWithMetadata,CollectionWithMetadata,AdminPolicyWithMetadata] cocina_object
+    # @return [DRO,Collection,AdminPolicy]
+    def self.without_metadata(cocina_object)
+      build(cocina_object.to_h.except(:created, :modified, :lock))
+    end
+
+    # Adds metadata to a DRO, Collection, AdminPolicy
+    # or updates for a DROWithMetadata, CollectionWithMetadata, AdminPolicyWithMetadata
+    # @param [DROWithMetadata,CollectionWithMetadata,
+    #           AdminPolicyWithMetadata,DRO,Collection,AdminPolicy] cocina_object
+    # @param [String] lock
+    # @param [DateTime] created
+    # @param [DateTime] modified
+    # @return [DROWithMetadata,CollectionWithMetadata,AdminPolicyWithMetadata]
+    def self.with_metadata(cocina_object, lock, created: nil, modified: nil)
+      props = cocina_object.to_h
+      props[:created] = created.iso8601 if created
+      props[:modified] = modified.iso8601 if modified
+      props[:lock] = lock
+
+      clazz = case cocina_object.type
+              when *DRO::TYPES
+                DROWithMetadata
+              when *Collection::TYPES
+                CollectionWithMetadata
+              else
+                AdminPolicyWithMetadata
+              end
+      clazz.new(props)
+    end
+
     def self.type_for(dyn)
       dyn.with_indifferent_access.fetch('type')
     rescue KeyError

data/lib/cocina/rspec/matchers.rb

@@ -11,16 +11,21 @@ module Cocina
       matcher :cocina_object_with do |**kwargs|
         kwargs.each do |cocina_section, expected|
           match do |actual|
-            expected.all? do |expected_key, expected_value|
-              # NOTE: there's no better method on Hash that I could find for this.
-              #        #include? and #member? only check keys, not k/v pairs
-              actual.public_send(cocina_section).to_h.any? do |actual_key, actual_value|
-                if expected_value.is_a?(Hash) && actual_value.is_a?(Hash)
-                  expected_value.all? { |pair| actual_value.to_a.include?(pair) }
-                else
-                  actual_key == expected_key && actual_value == expected_value
+            # created, modified, lock for *WithMetadata don't respond to all?
+            if expected.respond_to?(:all?)
+              expected.all? do |expected_key, expected_value|
+                # NOTE: there's no better method on Hash that I could find for this.
+                #        #include? and #member? only check keys, not k/v pairs
+                actual.public_send(cocina_section).to_h.any? do |actual_key, actual_value|
+                  if expected_value.is_a?(Hash) && actual_value.is_a?(Hash)
+                    expected_value.all? { |pair| actual_value.to_a.include?(pair) }
+                  else
+                    actual_key == expected_key && actual_value == expected_value
+                  end
                 end
               end
+            else
+              expected == actual.public_send(cocina_section)
             end
           end
         end

data/openapi.yml

@@ -31,6 +31,18 @@ paths:
       responses:
         '200':
           description: noop
+  /validate/DROWithMetadata:
+    post:
+      summary: Validate a DRO with object metadata
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DROWithMetadata'
+      responses:
+        '200':
+          description: noop
   /validate/Collection:
     post:
       summary: Validate a Collection
@@ -55,6 +67,18 @@ paths:
       responses:
         '200':
           description: noop
+  /validate/CollectionWithMetadata:
+    post:
+      summary: Validate a Collection with object metadata
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CollectionWithMetadata'
+      responses:
+        '200':
+          description: noop
   /validate/AdminPolicy:
     post:
       summary: Validate an AdminPolicy
@@ -79,6 +103,18 @@ paths:
       responses:
         '200':
           description: noop
+  /validate/AdminPolicyWithMetadata:
+    post:
+      summary: Validate an AdminPolicy with object metadata
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AdminPolicyWithMetadata'
+      responses:
+        '200':
+          description: noop
   /validate/Description:
     post:
       summary: Validate a Description
@@ -295,6 +331,14 @@ components:
           description: The license governing reuse of the Collection. Should be an IRI for known licenses (i.e. CC, RightsStatement.org URI, etc.).
           type: string
           nullable: true
+    # AdminPolicyWithMetadata schema should not be copied to sdr-api and dor-services-app.
+    AdminPolicyWithMetadata:
+      description: Admin Policy with addition object metadata.
+      type: object
+      additionalProperties: false
+      allOf:
+        - $ref: "#/components/schemas/AdminPolicy"
+        - $ref: "#/components/schemas/ObjectMetadata"
     AppliesTo:
       description: Property model for indicating the parts, aspects, or versions of the resource to which a
         descriptive element is applicable.
@@ -325,18 +369,28 @@ components:
     CatalogLink:
       type: object
       additionalProperties: false
-      required:
-        - catalog
-        - catalogRecordId
       properties:
         catalog:
           description: Catalog that is the source of the linked record.
           type: string
+          enum:
+            - symphony
+            - previous symphony
           example: symphony
+        refresh:
+          description: 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.
+          type: boolean
+          default: false
         catalogRecordId:
           description: Record identifier that is unique within the context of the linked record's catalog.
           type: string
           example: '11403803'
+      required:
+        - catalog
+        - catalogRecordId
+        - refresh
     CatkeyBarcode:
       description: The barcode associated with a DRO object based on catkey, prefixed with 36105
       type: string
@@ -414,6 +468,8 @@ components:
         - type
         - version
         - access
+        - administrative
+        - identification
     CollectionAccess:
       description: Access metadata for collections
       type: object
@@ -450,6 +506,14 @@ components:
             $ref: '#/components/schemas/CatalogLink'
         sourceId:
           $ref: '#/components/schemas/SourceId'
+    # CollectionWithMetadata schema should not be copied to sdr-api and dor-services-app.
+    CollectionWithMetadata:
+      description: Collection with addition object metadata.
+      type: object
+      additionalProperties: false
+      allOf:
+        - $ref: "#/components/schemas/Collection"
+        - $ref: "#/components/schemas/ObjectMetadata"
     Contributor:
       description: Property model for describing agents contributing in some way to
         the creation and history of the resource.
@@ -894,6 +958,8 @@ components:
         - label
         - type
         - version
+        - identification
+        - structural
     DROAccess:
       type: object
       additionalProperties: false
@@ -968,6 +1034,14 @@ components:
           type: array
           items:
             $ref: '#/components/schemas/Druid'
+    # DROWithMetadata schema should not be copied to sdr-api and dor-services-app.
+    DROWithMetadata:
+      description: DRO with addition object metadata.
+      type: object
+      additionalProperties: false
+      allOf:
+        - $ref: "#/components/schemas/DRO"
+        - $ref: "#/components/schemas/ObjectMetadata"
     Druid:
       type: string
       pattern: '^druid:[b-df-hjkmnp-tv-z]{2}[0-9]{3}[b-df-hjkmnp-tv-z]{2}[0-9]{4}$'
@@ -1158,6 +1232,7 @@ components:
         - label
         - type
         - version
+        - structural
     FileSetStructural:
       description: Structural metadata
       type: object
@@ -1191,6 +1266,8 @@ components:
           $ref: '#/components/schemas/DOI'
         sourceId:
           $ref: '#/components/schemas/SourceId'
+      required:
+        - sourceId
     Language:
       description: Languages, scripts, symbolic systems, and notations used in all
         or part of a resource or its descriptive metadata.
@@ -1343,6 +1420,25 @@ components:
       required:
         - type
         - digest
+    # ObjectMetadata schema should not be copied to sdr-api and dor-services-app.
+    ObjectMetadata:
+      description: Metadata for a cocina object.
+      type: object
+      additionalProperties: false
+      properties:
+        created:
+          description: When the object was created.
+          type: string
+          format: date-time
+        modified:
+          description: When the object was modified.
+          type: string
+          format: date-time
+        lock:
+          description: Key for optimistic locking. The contents of the key is not specified.
+          type: string
+      required:
+        - lock
     Presentation:
       description: Presentation data for the File.
       type: object

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cocina-models
 version: !ruby/object:Gem::Version
-  version: 0.69.2
+  version: 0.72.0
 platform: ruby
 authors:
 - Justin Coyne
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-03-15 00:00:00.000000000 Z
+date: 2022-04-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: deprecation
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: dry-struct
   requirement: !ruby/object:Gem::Requirement
@@ -293,6 +307,7 @@ files:
 - lib/cocina/models/admin_policy.rb
 - lib/cocina/models/admin_policy_access_template.rb
 - lib/cocina/models/admin_policy_administrative.rb
+- lib/cocina/models/admin_policy_with_metadata.rb
 - lib/cocina/models/administrative.rb
 - lib/cocina/models/applies_to.rb
 - lib/cocina/models/business_barcode.rb
@@ -304,6 +319,7 @@ files:
 - lib/cocina/models/collection.rb
 - lib/cocina/models/collection_access.rb
 - lib/cocina/models/collection_identification.rb
+- lib/cocina/models/collection_with_metadata.rb
 - lib/cocina/models/contributor.rb
 - lib/cocina/models/controlled_digital_lending_access.rb
 - lib/cocina/models/dark_access.rb
@@ -324,6 +340,7 @@ files:
 - lib/cocina/models/dro_access.rb
 - lib/cocina/models/dro_rights_description_builder.rb
 - lib/cocina/models/dro_structural.rb
+- lib/cocina/models/dro_with_metadata.rb
 - lib/cocina/models/druid.rb
 - lib/cocina/models/embargo.rb
 - lib/cocina/models/event.rb
@@ -341,6 +358,7 @@ files:
 - lib/cocina/models/location_based_access.rb
 - lib/cocina/models/location_based_download_access.rb
 - lib/cocina/models/message_digest.rb
+- lib/cocina/models/object_metadata.rb
 - lib/cocina/models/object_type.rb
 - lib/cocina/models/presentation.rb
 - lib/cocina/models/purl.rb
@@ -366,7 +384,10 @@ files:
 - lib/cocina/models/title.rb
 - lib/cocina/models/title_builder.rb
 - lib/cocina/models/validatable.rb
-- lib/cocina/models/validator.rb
+- lib/cocina/models/validators/catalog_links_validator.rb
+- lib/cocina/models/validators/dark_validator.rb
+- lib/cocina/models/validators/open_api_validator.rb
+- lib/cocina/models/validators/validator.rb
 - lib/cocina/models/version.rb
 - lib/cocina/models/vocabulary.rb
 - lib/cocina/models/world_access.rb

data/lib/cocina/models/validator.rb

@@ -1,49 +0,0 @@
-# frozen_string_literal: true
-
-module Cocina
-  module Models
-    # Perform validation against openapi
-    class Validator
-      def self.validate(clazz, attributes)
-        method_name = clazz.name.split('::').last
-        request_operation = root.request_operation(:post, "/validate/#{method_name}")
-
-        # JSON.parse forces serialization of objects like DateTime.
-        json_attributes = JSON.parse(attributes.to_json)
-        # Inject cocinaVersion if needed and not present.
-        if operation_has_cocina_version?(request_operation) && !json_attributes.include?('cocinaVersion')
-          json_attributes['cocinaVersion'] = Cocina::Models::VERSION
-        end
-
-        request_operation.validate_request_body('application/json', json_attributes)
-      rescue OpenAPIParser::OpenAPIError => e
-        raise ValidationError, e.message
-      end
-
-      # rubocop:disable Metrics/AbcSize
-      # rubocop:disable Metrics/CyclomaticComplexity
-      def self.operation_has_cocina_version?(request_operation)
-        schema = request_operation.operation_object.request_body.content['application/json'].schema
-        all_of_properties = Array(schema.all_of&.flat_map { |all_of| all_of.properties&.keys }).compact
-        one_of_properties = Array(schema.one_of&.flat_map { |one_of| one_of.properties&.keys }).compact
-        properties = Array(schema.properties&.keys)
-        (properties + all_of_properties + one_of_properties).include?('cocinaVersion')
-      end
-      # rubocop:enable Metrics/AbcSize
-      # rubocop:enable Metrics/CyclomaticComplexity
-      private_class_method :operation_has_cocina_version?
-
-      # rubocop:disable Style/ClassVars
-      def self.root
-        @@root ||= OpenAPIParser.parse(YAML.load_file(openapi_path), strict_reference_validation: true)
-      end
-      # rubocop:enable Style/ClassVars
-      private_class_method :root
-
-      def self.openapi_path
-        ::File.expand_path('../../../openapi.yml', __dir__)
-      end
-      private_class_method :openapi_path
-    end
-  end
-end