cocina-models 0.69.2 → 0.70.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 191508cff01be391223c83aba3e7c085e99b581a0f12a95dcd627572fbe5be36
-  data.tar.gz: b4eb3927706c3a5316f30d03d0352e742b3b0a72bf966cb9b0ed6bb593a0d48d
+  metadata.gz: ab6c36807c8585e07d8fc5529e6ef1aa08e88f7fc93d3dc7605aecb87e9138db
+  data.tar.gz: 8a5c302070e2beab4c3606124e1b68e64a1ab1063c8c32d05e47a66db3325d78
 SHA512:
-  metadata.gz: 8a4e9c462003e94e13992d20e2adc1a88515185820c11f851b0e709913addb541efadb35d11a0c841cb563e26d0b98cea15b0c0cc9d14aeddeb93f5bc953b147
-  data.tar.gz: 501f90b85f9386ff832b4147483d6e46fd6e8735fe87de6b868e7f68e2c6a02f1cf71759cb649103bcff93fb9e5830c11cd3ac0387e85336821237f8add0ee71
+  metadata.gz: 33fa2bd17896f666da8f4bdc1249a1e216f0344c0dc6d95e47b76a97b801a2ab1abf05fd1ca287e7bd23e134a34de8900e985e7db3bfea2e91b9c359be209722
+  data.tar.gz: 93ac31afd9d5da0587d4798c8e3ae571853f0e2b3c85d6edcda231ab886d9fd4f3559e7616a70f2290629028faa745bc40406f47f0bbe5ec95574bbe084bb532

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,6 +101,8 @@ 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).
 
+**[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:
@@ -112,7 +120,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/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/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/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/version.rb

@@ -2,6 +2,6 @@
 
 module Cocina
   module Models
-    VERSION = '0.69.2'
+    VERSION = '0.70.0'
   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.
@@ -414,6 +458,8 @@ components:
         - type
         - version
         - access
+        - administrative
+        - identification
     CollectionAccess:
       description: Access metadata for collections
       type: object
@@ -450,6 +496,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 +948,8 @@ components:
         - label
         - type
         - version
+        - identification
+        - structural
     DROAccess:
       type: object
       additionalProperties: false
@@ -968,6 +1024,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 +1222,7 @@ components:
         - label
         - type
         - version
+        - structural
     FileSetStructural:
       description: Structural metadata
       type: object
@@ -1343,6 +1408,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.70.0
 platform: ruby
 authors:
 - Justin Coyne
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-03-15 00:00:00.000000000 Z
+date: 2022-03-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -293,6 +293,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 +305,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 +326,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 +344,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
@@ -377,7 +381,7 @@ homepage: https://github.com/sul-dlss/cocina-models
 licenses: []
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -392,8 +396,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.32
-signing_key: 
+rubygems_version: 3.3.9
+signing_key:
 specification_version: 4
 summary: Data models for the SDR
 test_files: []