Skip to content

Instantly share code, notes, and snippets.

@patrickmj

patrickmj/DrsItemResponse.js

Last active October 27, 2023 19:00
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save patrickmj/d21cd457a813c6ba34703bf3dd16e96f to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save patrickmj/d21cd457a813c6ba34703bf3dd16e96f to your computer and use it in GitHub Desktop.
Download ZIP
Draft ideas for DRS API response
Raw
DrsItemResponse.js
/*
* This is an example single item API response, using the Image_Payload in this repo as a starting point.
*
* It merges how IIIf files and manifests are handled.
*
* It also includes simplified variations of the element names from XML. I think they align closely
* enough with the XML version to be recognizable without losing semantics, at least for what CERES
* needs.
*
* Elements below query and result are optional, unless otherwise noted (or if I don't get an HTTP 200 response,
* but that means I have other fish to fry).
*
* Please let me know if I've missed things or it needs other changes. PMJ
*
*/
var DrsItemResponse = {
"query": {
"pid": '', // the pid queried
"api_version": "v2",
"query_time": 3 // in millisceconds, for debuging/ performance w/in CERES
},
"result": {
"breadcrumbs":[// correct order, as they are now
{
"pid": "label"
}, {
"pid": "label"
}, {
"pid": "label"
}, {
"pid": "label"
}],
"parent": { // for broader context
"pid": 'pid',
"type": "collection|set"
},
"metadata": {
/*
* mods_files
*
* If there will never be more than one, just a simple object without the array.
* If there could be more than one, I'll want to consult with Sarah.
*
* required
*/
"mods_files": [ //required
{
"url": "URL to retrieve MODS record",
"lang": "en"
}
],
"mods_data": { // required
"dc": {
"en": {
"title": "the title",
"abstract": "",
"creator": "",
"created": ""
// all the other dc in en
},
"es": { // all the dc in es, just here as a placeholder in case someday we need such a thing
"title": "el titulo",
"abstract": ""
}
}
/* Other, non-DC data like Darwin Core or VRA would follow roughly
* the same pattern like
* "vra" : {
* "en" : {
* VRA elements
* },
* }
*
* VRA will be especially tricky if/when we get to all the sub- and sub-sub- elements
* (those kicked my ass and sub-sub-ass when I was doing the Omeka plugin for VRA).
*
* MODS
* */
},
"tags":[ "tag 1", "tag 2"] // array or null
},
/* representations
*
* URLs to representation files on disk for things like transcripts or an image to use for a podcast/oral history
* that don't really require getting full METS-based records so we can avoid a query but still render the page
*
*/
"representations": {
"transcript": 'https://', //url to directly retrieve the file
"closed_captioning": 'https://',
/*
* preview_url
*
* like a title card for a podcast episode;
* possibly distinct from thumbnails below? not sure about that one?
*/
"preview_url": 'https://',
"thumbnails":[ { //or just one for IIIF, and CERES calculates the size desired for different thumbnails?
"thumbnail_1": 'https://',
"fits" : 'https://',
"mimetype" : ""
},
{
"thumbnail_2": 'https://',
"fits" : 'https://',
"mimetype" : ""
},
{
"thumbnail_3": 'https://',
"fits" : 'https://',
"mimetype" : ""
}
],
/*
* iiifs
*
* This merges the distinct files and manifests from the XML
*
*/
"iiifs":[ {
"file": 'https://',
"manifest": 'https://'
}, {
"manifest": 'https://'
}, {
"file": 'https://',
"manifest": 'https://'
}]
}
}
}
Raw
DrsSearchResponse.js
/*
* This represents a proposed DRSv2 result for a search/browse query.
* It simplifies the single item response into just the data wanted for
* a simplified renderer for individual items in a search/browse page.
*
* The single item result from METS looks fine, with two possible changes:
* 1. Move thumbnails from Metadata into Representations
* 2. Renaming elements in METS to correspond with what JSON calls them here.
* That might irrelevant if the METS xml structure and naming works better for the
* DRS needs and DPS needs.
*/
var searchResponse = {
"query": {
"params": {
},
// tell me back the params for the query I sent for debugging my queries
"api_version": "v2",
"collection_pid/url": "url", //tell me back the collection (or set) I queried; could be useful
"per_page": 20, // or whatever the default is, or from query
"total_pages": 10,
"page": 2,
"next_page_url": "",
"prev_page_url": "",
"query_time": 3, // in millisceconds, for debuging/ performance w/in CERES
"total_items": 195
//TODO check with Rob about his thoughts on what's useful
},
"results":[// an array of objects for each returned item, condensed and simplified from individual items
{
//merging Metadata and Representations from METS payload cuz CERES won't care for interfaces
"dc": {
"title": '',
"abstract": '',
"subjects":[ {
"label": '',
"uri": '' //either DRS id or of Rights Statements or whatever
}],
"created": '', // as a dateTime
"creators":[ {
"label": '',
"uri": '' //either internal or Rights Statements or whatever
}],
"rights": {
}
// just the string, or object of human-readable text and/or URI to definition (CC, RightsStatements.org, etc)
},
"pid": '', // the biggie for chasing down the details for the individual item METS-based response
"notes":[// useful more on public side for showing rights info (types TBD with metadata folks)
{
"type": "a type label for the note", //hypothetical controlled vocab for note types; 'untyped' would be acceptable",
"note": "lorem blah whatevs"
}, {
}
// more of the same for multiple notes
],
"tags":[ 'tag1', 'tag2', 'tag a billion'], // useful on admin side for selecting; on public side for contextualizing
"parent": { // for broader context
"pid": "pid",
"type": "collection|set"
},
/* file_type
*
* to signal what kind of thing is in the preview (PDF, Image, Video, etc)
* biggest thing here is to know what HTML element to use so a browse page
* can say say what kind content is coming their way
*
* When there are multiple files, use the main one for the item
*/
"file_type": '',
/* representations
*
* URLs to representation files on disk for things like transcripts or an image to use for a podcast/oral history
* that don't really require getting full METS-based records so we can avoid a query but still render the page
*
*/
"representations": {
"transcript": 'https:', //url to directly retrieve the file
"closed_captioning": 'https:',
"preview": { // like an image for a podcast episode, distinct from thumbnails; see the corresponding discussion in DrsItemResponse
"url" : "https",
"mimetype" : "image/jpeg"
},
"thumbnails":[ // etc, or just one for IIIF?
{
"thumbnail_1": {
"url":'https:', "mime_type": "image/jpeg",
"mimetype" : ""
}
},
{
"thumbnail_2": {
"url":'https:', "mime_type": "image/jpeg",
"mimetype" : ""
}
},
{
"thumbnail_3": {
"url":'https:', "mime_type": "image/jpeg",
"mimetype" : ""
}
}
]
},
"coords": { // if a project is very location-based, a browse page that is basically a map might be useful
"lat": '', "lng": '' // or null (or nil for you Ruby types)
},
// drs_ info helpful on admin side for selecting items for galleries etc.
"drs_created": '', //date created in DRS as dateTime (also a query param?)
"drs_creator": {
"name": '', 'id': ''
},
//Who submitted the item to the DRS; not sure how much data to expose here (also a query param?)
"drs_modified": '' // as a dateTime (also a query param?)
}, {
}
// more of the same
]
}
Raw
Image_Payload.json
{
"payload": {
"Work": {
"Metadata": {
"MODS_Files": {
"MODS_File": {
"order": 0,
"url": "URL to retrieve MODS record",
"lang": "en"
}
}
},
"Representations": {
"Thumbnail_files": {
"Thumbnail_File": [
{
"label": "Thumbnail 1",
"order": 0,
"url": "URL to retrieve Class 1 Thumbnail",
"mimetype": "image/jpeg"
},
{
"label": "Thumbnail 2",
"order": 0,
"url": "URL to retrieve Class 2 Thumbnail",
"mimetype": "image/jpeg"
},
{
"label": "Thumbnail 3",
"order": 0,
"url": "URL to retrieve Class 3 Thumbnail",
"mimetype": "image/jpeg"
},
{
"label": "Thumbnail 4",
"order": 0,
"url": "URL to retrieve Class 4 Thumbnail",
"mimetype": "image/jpeg"
},
{
"label": "Thumbnail 5",
"order": 0,
"url": "URL to retrieve Class 5 Thumbnail",
"mimetype": "image/jpeg"
}
]
},
"Image_Files": {
"Image_File": [
{
"order": 1,
"url": "URL to retrieve image from disk",
"fits": "URL to retrieve FITS record for 1st Page Image",
"mimetype": "image/tiff"
},
{
"order": 2,
"url": "URL to retrieve image from disk",
"fits": "URL to retrieve FITS record for 2nd Page Image",
"mimetype": "image/tiff"
}
]
},
"IIIF_Image_Files": {
"IIIF_Image_File": [
{
"order": 1,
"url": "URL to retrieve IIIF Image"
},
{
"order": 2,
"url": "URL to retrieve IIIF Image"
}
]
},
"IIIF_Manifest_Files": {
"IIIF_Manifest_File": {
"order": 0,
"url": "URL to retrieve IIIF Manifest"
}
}
}
}
}
}
Raw
Image_Payload.xml
<?xml version="1.0" encoding="UTF-8"?>
<!--
This is only slighty modified from 3FP's example.
If moves the thumbnails into the <Representations> section
rather than <Metadata>.
-->
<payload>
<Work>
<Metadata>
<MODS_Files>
<MODS_File>
<order>0</order>
<url>URL to retrieve MODS record</url>
<lang>en</lang>
</MODS_File>
</MODS_Files>
</Metadata>
<Representations>
<Thumbnail_files>
<Thumbnail_File>
<label>Thumbnail 1</label>
<order>0</order>
<url>URL to retrieve Class 1 Thumbnail</url>
<mimetype>image/jpeg</mimetype>
</Thumbnail_File>
<Thumbnail_File>
<label>Thumbnail 2</label>
<order>0</order>
<url>URL to retrieve Class 2 Thumbnail</url>
<mimetype>image/jpeg</mimetype>
</Thumbnail_File>
<Thumbnail_File>
<label>Thumbnail 3</label>
<order>0</order>
<url>URL to retrieve Class 3 Thumbnail</url>
<mimetype>image/jpeg</mimetype>
</Thumbnail_File>
<Thumbnail_File>
<label>Thumbnail 4</label>
<order>0</order>
<url>URL to retrieve Class 4 Thumbnail</url>
<mimetype>image/jpeg</mimetype>
</Thumbnail_File>
<Thumbnail_File>
<label>Thumbnail 5</label>
<order>0</order>
<url>URL to retrieve Class 5 Thumbnail</url>
<mimetype>image/jpeg</mimetype>
</Thumbnail_File>
</Thumbnail_files>
<Image_Files>
<Image_File>
<order>1</order>
<url>URL to retrieve image from disk</url>
<fits>URL to retrieve FITS record for 1st Page Image</fits>
<mimetype>image/tiff</mimetype>
</Image_File>
<Image_File>
<order>2</order>
<url>URL to retrieve image from disk</url>
<fits>URL to retrieve FITS record for 2nd Page Image</fits>
<mimetype>image/tiff</mimetype>
</Image_File>
</Image_Files>
<IIIF_Image_Files>
<IIIF_Image_File>
<order>1</order>
<url>URL to retrieve IIIF Image</url>
</IIIF_Image_File>
<IIIF_Image_File>
<order>2</order>
<url>URL to retrieve IIIF Image</url>
</IIIF_Image_File>
</IIIF_Image_Files>
<IIIF_Manifest_Files>
<IIIF_Manifest_File>
<order>0</order>
<url>URL to retrieve IIIF Manifest</url>
</IIIF_Manifest_File>
</IIIF_Manifest_Files>
</Representations>
</Work>
</payload>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment