cocina_display 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1e3637cdbaae1a3227f2cfac3186ea15648151c0d90e5d71f678d32bb4242487
+  data.tar.gz: 12ee8a16fc75ff83361bbc929d3d15693f9dcf121585d61654c8cd5da60ca2d8
+SHA512:
+  metadata.gz: 02cea2ac8bbb9ecab1d142f48e78d237762d6394615f87aed6a9aa535f2d34e2bea6b3d4629e0851853e9b8708d2578d26c9e1baec8a0a7c952c7c1d8deffc4a
+  data.tar.gz: ba18d7424b7114525a5100bf73b619e9dbae259e2ec35fb6f0a754981457d8c67b6f686c3a4d53ef98f29122291fd564e6768fb2a348744e3e54813df3b03049

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.1

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2025 The Board of Trustees of the Leland Stanford Junior University.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,112 @@
+# CocinaDisplay
+
+[![Build Status](https://github.com/sul-dlss/cocina_display/workflows/CI/badge.svg)](https://github.com/sul-dlss/cocina_display/actions)
+[![Docs Status](https://github.com/sul-dlss/cocina_display/actions/workflows/docs.yml/badge.svg)](https://github.com/sul-dlss/cocina_display/actions/workflows/docs.yml)
+[![Gem Version](https://badge.fury.io/rb/cocina_display.svg)](https://badge.fury.io/rb/cocina_display)
+
+Helpers for rendering Cocina metadata in Rails applications and indexing pipelines.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add cocina_display
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install cocina_display
+```
+
+## Usage
+
+### Obtaining Cocina
+
+To start, you need some Cocina in JSON form. 
+
+You can download some directly from PURL by visiting an object's PURL URL and appending `.json` to the end, like `https://purl.stanford.edu/bb112zx3193.json`. Some examples are available in the `spec/fixtures` directory.
+
+You can also use the built-in `HTTP` library or `faraday` gem to fetch the record for you, e.g.:
+
+```ruby
+require 'http'
+cocina_json = HTTP.get('https://purl.stanford.edu/bb112zx3193.json').to_s
+```
+
+### Working with objects
+
+Once you have the JSON, you can initialize a `CocinaRecord` object and start working with it. The `CocinaRecord` class provides some methods to access common fields, as well as an underlying hash representation parsed from the JSON.
+
+```ruby
+> require 'cocina_display/cocina_record'
+=> true
+> record = CocinaDisplay::CocinaRecord.new(cocina_json)
+=>
+#<CocinaDisplay::CocinaRecord:0x000000012d11b600
+...
+> record.titles
+=> ["Bugatti Type 51A. Road & Track Salon January 1957"]
+> record.content_type
+=> "image"
+> record.iiif_manifest_url 
+=> "https://purl.stanford.edu/bb112zx3193/iiif3/manifest"
+> record.cocina_doc.dig("description", "contributor", 0, "name", 0, "value")  # access the hash representation
+=> "Hearst Magazines, Inc."
+```
+
+See the [API Documentation](https://sul-dlss.github.io/cocina_display/CocinaDisplay/CocinaRecord.html) for more details on the methods available in the `CocinaRecord` class.
+
+### Fetching nested data
+
+Fetching data deeply nested in the record, especially when you need to filter based on some criteria, can be tedious. The `CocinaRecord` class also provides a method called `#path` that accepts a JsonPath expression to retrieve data in a more concise way.
+
+The previous example used `Hash#dig` to access the first contributor's first name value. Using `#path`, you can query for _all_ contributor name values, or even filter to particular contributors:
+
+```ruby
+> record.path('$.description.contributor[*].name[*].value').search # name values for all contributors in description
+=> ["Hearst Magazines, Inc.", "Chesebrough, Jerry"]
+> record.path("$.description.contributor[?@.role[?@.value == 'photographer']].name[*].value").search # only contributors with a role with value "photographer"
+=> ["Chesebrough, Jerry"]
+> 
+```
+
+The JsonPath implementation used is [`janeway-jsonpath`](https://www.rubydoc.info/gems/janeway-jsonpath/0.6.0/file/README.md), which supports the full syntax from the [finalized 2024 version of the specification](https://www.rfc-editor.org/rfc/rfc9535.html). Results returned from `#path` are Enumerators.
+
+In the following example, we start an expression with `"$.."` to search for contributor nodes at _any_ level (e.g. `event.contributors`) and discover that there is a third contributor, but it has no `name` value. Using the `['code', 'value']` syntax, we can retrieve both `code` and `value` and show where they came from:
+
+```ruby
+> record.path("$..contributor[*].name[*]['code', 'value']").each { |value, node, key| puts "#{key}: #{value} (from #{node})" }
+value: Hearst Magazines, Inc. (from {"structuredValue"=>[], "parallelValue"=>[], "groupedValue"=>[], "value"=>"Hearst Magazines, Inc.", "uri"=>"http://id.loc.gov/authorities/names/n2015050736", "identifier"=>[], "source"=>{"code"=>"naf", "uri"=>"http://id.loc.gov/authorities/names/", "note"=>[]}, "note"=>[], "appliesTo"=>[]})
+value: Chesebrough, Jerry (from {"structuredValue"=>[], "parallelValue"=>[], "groupedValue"=>[], "value"=>"Chesebrough, Jerry", "identifier"=>[], "note"=>[], "appliesTo"=>[]})
+code: CSt (from {"structuredValue"=>[], "parallelValue"=>[], "groupedValue"=>[], "code"=>"CSt", "uri"=>"http://id.loc.gov/vocabulary/organizations/cst", "identifier"=>[], "source"=>{"code"=>"marcorg", "uri"=>"http://id.loc.gov/vocabulary/organizations", "note"=>[]}, "note"=>[], "appliesTo"=>[]})
+=> ["Hearst Magazines, Inc.", "Chesebrough, Jerry", "CSt"]
+```
+
+There is also a command line utility for quickly querying a JSON file using JsonPath. Online syntax checkers may give different results, so it helps to test locally. You can run it with:
+
+```bash
+cat spec/fixtures/bb112zx3193.json | janeway "$.description.contributor[?@.role[?@.value == 'photographer']].name[*].value"
+[
+  "Chesebrough, Jerry"
+]
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+Documentation is generated using [yard](https://yardoc.org). You can generate it by running `yardoc`, or `yard server --reload` to start a local server and watch for changes as you edit.
+
+## Background
+
+Historically, applications at SUL used a combination of several gems to render objects represented by MODS XML. With the transition to the Cocina data model, infrastructure applications adopted the [`cocina-models` gem](https://github.com/sul-dlss/cocina-models), which provides accessor objects and validators over Cocina JSON. Internal applications can fetch such objects over HTTP using [`dor-services-client`](https://github.com/sul-dlss/dor-services-client).
+
+On the access side, Cocina JSON (the "public Cocina") is available statically via [PURL](https://purl.stanford.edu), but is only updated when an object is published ("shelved") from SDR. This frequently results in data that is technically invalid with respect to `cocina-models` but is still valid in the context of a patron-facing application.
+
+Cocina data can also be complex, representing the same underlying information in different ways. A "complete" implementation can involve checking multiple deeply nested paths to ensure no information is missed. Rather than tightly coupling access applications to `cocina-models`, this gem provides a set of helpers designed to safely parse Cocina JSON and render it in a consistent way across applications.
+
+The intent is that both applications that directly render SDR metadata as HTML (PURL, Exhibits) and applications that index it for later display in a catalog (Searchworks, Earthworks, Dataworks) can adopt a single gem for rendering Cocina in a human-readable way. This gem **does not** aim to render HTML or provide view components – that is the responsibility of the consuming application.

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/lib/cocina_display/cocina_record.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "cocina/models"
+require "janeway"
+
+module CocinaDisplay
+  # Public Cocina metadata for an SDR object
+  class CocinaRecord
+    # The parsed Cocina document.
+    # @return [Hash]
+    attr_reader :cocina_doc
+
+    def initialize(cocina_json)
+      @cocina_doc = JSON.parse(cocina_json)
+    end
+
+    # Evaluate a JSONPath expression against the Cocina document.
+    # @return [Enumerator] An enumerator that yields results matching the expression.
+    # @param path_expression [String] The JSONPath expression to evaluate.
+    # @see https://www.rubydoc.info/gems/janeway-jsonpath/0.6.0/file/README.md
+    # @example Name values for contributors
+    #  record.path("$.description.contributor[*].name[*].value").search #=> ["Smith, John", "ACME Corp."]
+    # @example Filtering nodes using a condition
+    #  record.path("$.description.contributor[?(@.type == 'person')].name[*].value").search #=> ["Smith, John"]
+    def path(path_expression)
+      Janeway.enum_for(path_expression, cocina_doc)
+    end
+
+    # The DRUID for the object, with the +druid:+ prefix.
+    # @return [String]
+    # @example
+    #   record.druid #=> "druid:bb099mt5053"
+    def druid
+      cocina_doc["externalIdentifier"]
+    end
+
+    # The DRUID for the object, without the +druid:+ prefix.
+    # @return [String]
+    # @example
+    #   record.bare_druid #=> "bb099mt5053"
+    def bare_druid
+      druid.delete_prefix("druid:")
+    end
+
+    # The DOI for the object, if there is one – just the identifier part.
+    # @return [String, nil]
+    # @example
+    #   record.doi #=> "10.25740/ppax-bf07"
+    def doi
+      doi_id = path("$.identification.doi").first ||
+        path("$.description.identifier[?match(@.type, 'doi|DOI')].value").first ||
+        path("$.description.identifier[?search(@.uri, 'doi.org')].uri").first
+
+      URI(doi_id).path.delete_prefix("/") if doi_id.present?
+    end
+
+    # The DOI as a URL, if there is one. Any valid DOI should resolve via doi.org.
+    # @return [String, nil]
+    # @example
+    #   record.doi_url #=> "https://doi.org/10.25740/ppax-bf07"
+    def doi_url
+      URI.join("https://doi.org", doi).to_s if doi.present?
+    end
+
+    # The HRID of the item in FOLIO, if defined.
+    # @note This doesn't imply the object is available in Searchworks at this ID.
+    # @return [String, nil]
+    # @example
+    #   record.folio_hrid #=> "a12845814"
+    def folio_hrid
+      path("$.identification.catalogLinks[?(@.catalog == 'folio')].catalogRecordId").first
+    end
+
+    # The FOLIO HRID if defined, otherwise the bare DRUID.
+    # @note This doesn't imply the object is available in Searchworks at this ID.
+    # @see folio_hrid
+    # @see bare_druid
+    # @return [String]
+    def searchworks_id
+      folio_hrid || bare_druid
+    end
+
+    # Timestamp when the Cocina was created.
+    # @note This is for the metadata itself, not the object.
+    # @return [Time]
+    def created_time
+      Time.parse(cocina_doc["created"])
+    end
+
+    # Timestamp when the Cocina was last modified.
+    # @note This is for the metadata itself, not the object.
+    # @return [Time]
+    def modified_time
+      Time.parse(cocina_doc["modified"])
+    end
+
+    # SDR content type of the object.
+    # @return [String]
+    # @see https://github.com/sul-dlss/cocina-models/blob/main/openapi.yml#L532-L546
+    # @example
+    #  record.content_type #=> "image"
+    def content_type
+      cocina_doc["type"].split("/").last
+    end
+
+    # True if the object is a collection.
+    # @return [Boolean]
+    def collection?
+      content_type == "collection"
+    end
+
+    # Traverse nested FileSets and return an enumerator over their files.
+    # Each file is a +Hash+.
+    # @return [Enumerator] Enumerator over file hashes
+    # @example
+    #  record.files.each do |file|
+    #   puts file["filename"] #=> "image1.jpg"
+    #   puts file["size"] #=> 123456
+    #  end
+    def files
+      path("$.structural.contains[*].structural.contains[*]")
+    end
+
+    # The PURL URL for this object.
+    # @return [String]
+    # @example
+    #  record.purl_url #=> "https://purl.stanford.edu/bx658jh7339"
+    def purl_url
+      cocina_doc.dig("description", "purl") || "https://purl.stanford.edu/#{bare_druid}"
+    end
+
+    # The URL to the PURL environment this object is from.
+    # @note Objects accessed via UAT will still have a production PURL base URL.
+    # @return [String]
+    # @example
+    #   record.purl_base_url #=> "https://purl.stanford.edu"
+    def purl_base_url
+      URI(purl_url).origin
+    end
+
+    # The URL to the stacks environment this object is shelved in.
+    # Corresponds to the PURL environment.
+    # @see purl_base_url
+    # @return [String]
+    # @example
+    #  record.stacks_base_url #=> "https://stacks.stanford.edu"
+    def stacks_base_url
+      if purl_base_url == "https://sul-purl-stage.stanford.edu"
+        "https://sul-stacks-stage.stanford.edu"
+      else
+        "https://stacks.stanford.edu"
+      end
+    end
+
+    # The oEmbed URL for the object, optionally with additional parameters.
+    # Corresponds to the PURL environment.
+    # @param params [Hash] Additional parameters to include in the oEmbed URL.
+    # @return [String]
+    # @return [nil] if the object is a collection.
+    # @example Generate an oEmbed URL for the viewer and hide the title
+    #   record.oembed_url(hide_title: true) #=> "https://purl.stanford.edu/bx658jh7339/embed.json?hide_title=true"
+    def oembed_url(params: {})
+      return if collection?
+
+      params[:url] ||= purl_url
+      "#{purl_base_url}/embed.json?#{params.to_query}"
+    end
+
+    # The download URL to get the entire object as a .zip file.
+    # Stacks generates the .zip for the object on request.
+    # @return [String]
+    # @example
+    #   record.download_url #=> "https://stacks.stanford.edu/object/bx658jh7339"
+    def download_url
+      "#{stacks_base_url}/object/#{bare_druid}"
+    end
+
+    # The IIIF manifest URL for the object.
+    # PURL generates the IIIF manifest.
+    # @param version [Integer] The IIIF presentation spec version to use (3 or 2).
+    # @return [String]
+    # @example
+    #  record.iiif_manifest_url #=> "https://purl.stanford.edu/bx658jh7339/iiif3/manifest"
+    def iiif_manifest_url(version: 3)
+      iiif_path = (version == 3) ? "iiif3" : "iiif"
+      "#{purl_url}/#{iiif_path}/manifest"
+    end
+  end
+end

data/lib/cocina_display/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# :nodoc:
+module CocinaDisplay
+  VERSION = "0.1.0" # :nodoc:
+end

data/lib/cocina_display.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "cocina_display/version"
+require_relative "cocina_display/cocina_record"

data/sig/cocina_display.rbs

@@ -0,0 +1,4 @@
+module CocinaDisplay
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,152 @@
+--- !ruby/object:Gem::Specification
+name: cocina_display
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nick Budak
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-06-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: cocina-models
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.101'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.101'
+- !ruby/object:Gem::Dependency
+  name: janeway-jsonpath
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.22.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.22.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.37
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.37
+description:
+email:
+- budak@stanford.edu
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".standard.yml"
+- LICENSE
+- README.md
+- Rakefile
+- lib/cocina_display.rb
+- lib/cocina_display/cocina_record.rb
+- lib/cocina_display/version.rb
+- sig/cocina_display.rbs
+homepage: https://sul-dlss.github.io/cocina_display/
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://sul-dlss.github.io/cocina_display/
+  source_code_uri: https://github.com/sul-dlss/cocina_display
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Helpers for rendering Cocina metadata
+test_files: []