Item Core Model

By ScienceBase Instructions and Documentation

The following documentation describes the ScienceBase item core elements, how those elements are related to applicable metadata standards, how the elements are used in ScienceBase, and the sbJSON syntax used to store content in the ScienceBase system.

The ScienceBase Item Core is based on the Dublin Core Metadata Element Set and includes additional elements that may or may not be associated with other metadata standards. It integrates multiple metadata standards, conventions, and practices to describe a wide array of scientific data and information assets important to science teams using ScienceBase.

The following documentation describes the ScienceBase core elements and the JSON syntax used to store content in the ScienceBase system. The JSON format can be transformed into various forms of XML and other outputs to support interactions with ScienceBase. The Item Core model can be extended with additional sets of JSON elements called extensions (or facets).

For more detailed information, please contact sciencebase@usgs.gov. USGS users have access to additional internal documentation and instructional materials.

To view the JSON content of any item in ScienceBase, add "?format=json" to the URL, for example, https://www.sciencebase.gov/catalog/item/58f7fadae4b0b7ea5451fc5c?format=json.

The Fields

link

Datatype: Hashmap (non-editable)
These are the standard JSON links. "rel" tells you what you are looking at. For items, this will always be "self". In search results, you may also have nextlink and prevlink which have the same properties as link (rel, url) and point to the next and previous pages respectively. You do not need to pass this in to create an item because it will be automatically generated.

"link":{"rel":"self","url":"<full url of item or search>","nextlink":{"rel":"next","url":"<url of next result>"},"prevlink":{"rel":"prev","url":"<url of previous result>"}}

relatedItems

Datatype: Object (non-editable)
The URL of the page that displays an item's relationships with associated ScienceBase items.

"relatedItems": { "link": { "url": "https://www.sciencebase.gov/catalog/itemLinks?itemId=5640edd5e4b0831b7d…", "rel": "related" } }

id

Datatype: String (non-editable)
The unique ScienceBase id of the item. ScienceBase assigns its own universally unique identifier to every item and uses it consistently throughout the architecture for all references. The UUID may be expressed as an HTTP URI (universal resource identifier) in some circumstances, but the basic ID is listed as a UUID string in the core model.

"id":"<unique id>"

identifiers

Datatype: Array of identifier objects.
ScienceBase Items may have many other identifiers associated with them that may be unique within some particular context such as a source system. Other identifiers are stored as a type/scheme/key combination and will be unique within that full schema.

identifier Object

type
Datatype: String
The type of identifier, for example an API Number, DOI, or Project Number

scheme
Datatype: String
The identification scheme is used to identify unique records in a set. Typically this is a URL to the scheme that describes the tag type.

key
Datatype: String
The identifier for this item.

"identifiers": [{"type":"Type","scheme":"Scheme","key":"Key"},{"type":"Type2", "scheme":"Scheme2", "key":"Key2"}]

title

Datatype: String
Title is one of the most important ScienceBase attributes because it is used everywhere to give users a quick description of an item. ScienceBase has many different types of items coming from many sources, and titles need to be written so that they can be generally understood outside a particular context.

Titles are used as the item page's title so titles can show up in search results like Google.

"title":"Item Title"

subTitle

Datatype: String
A subtitle may be an explanatory or alternate title that provides additional information about the item. The subtitle may clarify the theme of the item, enhancing the title.

"subTitle":"Item Subtitle"

alternateTitles

Datatype: Array of Strings
A ScienceBase item can have any number of alternate titles used to describe the item. Alternate titles are used at times for harvested items when a new primary title field is crafted so that an item makes better sense outside its original context. Alternate titles help users understand a little more about an item and how it may be referenced in other places.

"alternateTitles":["Alternate Titles","Alternate Titles 2","Alternate Titles 3"]

summary

Datatype: String (non-editable)
A concatenated version of the body auto generated by ScienceBase.

"summary":"The main goal of this item is to show you how to create an item"

body

Datatype: String
The ScienceBase Body is an open descriptive field for an item that may contain rich formatting (accessible by clicking the arrow button at the top right of the form field). The Body should provide users with a clear understanding of an item with as much formatting as necessary to give the user a clear reading experience.

For some types of items, the Body may constitute the sum total of an item. Such is the case with ScienceBase Information Articles, which are items stored natively in ScienceBase to contain important informational content about some topic.

The Body field for some harvested items may be constructed by putting together several original fields of information that do not need to be kept separate for the ScienceBase presentation of those items.

The body can contain limited html markup which will be rendered on the item page.

"body":"The main goal of this item is to show you how to create an item"

citation

Datatype: String
The citation that can be used to reference the item.

"citation":"Vanderhoof, M.K., Lane, C.R., McManus, M.G., Alexander, L.C., and Christensen, J.R., 2018, Data release for Wetlands inform how climate extremes influence surface water expansion and contraction: U.S. Geological Survey data release, https://doi.org/10.5066/F7GX49VQ."

purpose

Datatype: String
The Purpose field in ScienceBase is an open text field that may contain a statement about the intended purpose of a given item. It can be used to describe the intended or appropriate uses of a given dataset from the standpoint of its originator. It is meant for informational purposes only and does map to several metadata standards that make use of the field.

"purpose":"Purpose"

rights

Datatype: String
Rights for cataloged information items refer to intellectual property restrictions. Permissions from data provider may be required for using information. Manuscript access may require fees.

"rights":"Rights"

provenance

Datatype: Provenance object
The ScienceBase Provenance attribute is an open text field that is used to describe the origin of an item, especially in terms of how the item came to be introduced to ScienceBase. It can be used to describe the full provenance of some form of data that may have been through a number of derivations.

provenance Object

annotation
Datatype: String
The text of the provenance.

dataSource
Datatype: String
Where the item came from. If this item was created by a person in ScienceBase it will be "Input Directly". If it was harvested from an external source this will show that instead.

dateCreated
Datatype: DateTime
The date and time the item was created.

createdBy
Datatype: String
The person or organization who created the item.

lastUpdated
Datatype: DateTime
The date and time the item was last updated.

lastUpdatedBy
Datatype: String
The last person or organization to update the item.

"provenance": { "annotation":"Provenance1", "dataSouce":"Input directly", "dateCreated":"2015-11-09T19:02:45Z", "lastUpdated":"2015-11-09T19:02:45Ze", "lastUpdatedBy":"abc@usgs.gov", "createdBy":"abc@usgs.gov", "fileProcess": ???, "linkProcess": ??? }

materialRequestInstructions

Datatype: String
Material Request Instructions may include information about obtaining access to items, information, or physical samples (such as geologic specimens) that may not be available online. Information may include phone numbers, addresses, websites links, and office hours.

"materialRequestInstructions":"Material Request Instructions"

hasChildren

Datatype: Boolean (non-editable)
A boolean value that tells you whether or not an item has children (is a folder).

"hasChildren":false

parentId

Datatype: String – restricted to valid item ids
The unique ScienceBase id of the parent of this item. This is a string. This is one of two required fields in creating a new item, the other field is title.

"parentId":"4f46607504a61aa9773f463d"

contacts

Datatype: Array of contact objects
The contacts of an item. This is an collection of basic typed contact objects, which have the fields: type, name, highlighted. The type is the type of contact, e.g., Author, Contact, Data Owner, Participant, Principle Investigator, Project Chief, Associate Project Chief, Task Leader, this is a string. The name is the name of the contact, it is a string. Highlighted is whether or not the contact is highlighted, it is a boolean.

contact Object

Most fields in the contact object are self explanatory, but some are explained below. Check out the JSON object containing one person and one organization for full list of fields.

name (Datatype: String) The name of the contact.
contactType (Datatype: String) The type of contact, always "person" or "organization"
type (Datatype: String) An editable type to describe the person or organization.
email (Datatype: String) The email address of a person. Not included in organizations.
firstName¹ (Datatype: String)
middleName¹ (Datatype: String)
lastName¹ (Datatype: String)
jobTitle¹ (Datatype: String)
active (Datatype: Boolean) Whether the person or organization is active.
organization¹ (Datatype: Object with one field: displayText which describes the organization) Person types only.
primaryLocation (Datatype: primaryLocation object)
note² (Datatype: String)
aliases² (Datatype: Array of Strings)
logoUrl² (Datatype: URI)

¹ Only included on contactType "person"
² Only included on contactType "organization"

contacts: [ { name: "Robert N Prescott", oldPartyId: 58818, type: "Distributor", sourceId: "asdf", contactType: "person", organizationsPerson: "usgs", ttyPhone: "123-123-1234", hours: "8-4", instructions: "test", email: "rprescott@usgs.gov", active: true, jobTitle: "Computer Programmer", personalTitle: "test", firstName: "Robert", middleName: "N", lastName: "Prescott", organization: { displayText: "Fort Collins Science Center" }, primaryLocation: { shortName: "asdf", name: "Robert N Prescott/BRD/CONT/USGS/DOI - Primary Location", description: "asdf", location: "asdf", building: "NRRC Bldg C", buildingCode: "KBA", roomNumber: "123", officePhone: "9702269250", faxPhone: "9702269230", latitude: 20, longitude: 20, streetAddress: { line1: "2150 Centre Avenue Bldg C", line2: "sadf", mailStopCode: "safd", city: "Fort Collins", state: "CO", zip: "80526", country: "asdf" }, mailAddress: { line1: "2150 Centre Avenue, Building C", line2: "asdf", mailStopCode: "asdf", city: "Fort Collins", state: "CO", zip: "80526-8118", country: "USA" } } }, { name: "USGS Volcano Science Center", oldPartyId: 17471, type: "Cooperator/Partner", highlighted: true, sourceId: "the source", contactType: "organization", organizationsPerson: "tsets", ttyPhone: "123-123-1234", hours: "9-5", instructions: "inst", email: "test@test.com", note: "moved to REx for Alaska per Tammy Bagley", active: true, aliases: [ "VOLCANO HAZARDS TEAM", "VOLCANO SCIENCE CENTER" ], fbmsCodes: [ "GGWAWC0000" ], logoUrl: "http://my.usgs.gov/static-cache/images/dataOwner/v1/logosMed/USGSLogo.g…", smallLogoUrl: "http://my.usgs.gov/static-cache/images/dataOwner/v1/logosSmall/USGSLogo…", organization: { }, primaryLocation: { shortName: "asdf", name: "Cascades Vol Observatory - COLUMBIA TECH CENTER [WWA]", description: "asdf", location: "asdf", building: "COLUMBIA TECH CENTER", buildingCode: "WWA", roomNumber: "asdf", officePhone: "asdf", faxPhone: "asdfasdf", latitude: 12, longitude: 12, streetAddress: { line1: "1300 SE Cardinal Court, Bldg. 10", city: "Vancouver", state: "WA", zip: "98683-9589", country: "USA" }, mailAddress: { line1: "1300 SE Cardinal Court, Bldg. 10, Suite 100", city: "Vancouver", state: "WA", zip: "98683", country: "USA" } } } ]

weblink

Datatype: Array of weblink objects
These are the external web links of an item. This can include things such as an image, external documentation, or external download. This is a collection of webLink objects. Each webLink object has the fields type, uri, rel, title, and hidden.

weblink Object

type
Datatype: String
The type is a string which represents the type of URL this is, eg. 'webLink', 'download', 'Browse Image', etc. We use most of these types to do specific things, like show an image on the page and combine all the downloads to one button, so make sure that you are using the correct and exact values that are using in the ScienceBase GUI app. To test what this might be create a test item in ScienceBase, create a few "External Sources" with the types that you want and do a GET on the item with the Firefox RESTClient or similar tool.

typeLabel
Datatype: String
The human readable label for the weblink type.

uri
Datatype: URI
The URI or URL of the link. This is a string that must match normal URL standards, including starting with "http://", or the webLink will not be saved.

rel
Datatype: String
The related field. This is used by ScienceBase, but can be left blank in most weblinks.

title
Datatype: String
The title of the weblink.

hidden
Datatype: Boolean
Whether the webLink is hidden on the view page or not. Generally this will be false.

"webLinks": [ { "type":"download", "typeLabel": "Download", "uri":"http://URI.com/", "rel":"related", "title":"Title", "hidden":false }, { "type":"browseImage", "typeLabel": "Browse Image", "uri":"http://URI2.com/", "title":"Title2", "hidden":false } ]

browseCategories

Datatype: Array of strings
A type of tag that defines the category of an item. These are mostly set internally by ScienceBase.

"browseCategories": [ "Data", "Publication", "Project", "Physical Item" ]

browseTypes

Datatype: Array of strings
A type of tag that defines the type of item this is. These are mostly set internally by ScienceBase.

"browseTypes": [ "Collection", "ArcGIS REST Map Service", "Map Service", "ArcIMS Catalog", "Citation" ]

systemTypes

Datatype: Array of strings
The "system type" of an item. These are set internally by ScienceBase.

"systemTypes": [ "Mappable", "Folder" "Data Release" ]

dates

Datatype: Array of date objects
This can be the Start Date, the End Date, the date of publication or award, or any general date ("Info Date") associated with the record. There must be at least one date associated with any record.

date object

dateString
Datatype: Date
The date. Note that this dateString must be in the format: YYYY, YYYY-MM, or YYYY-MM-DD or the date will not be saved.

type
Datatype: String
The type of date.

label
Datatype: String
The human readable label for the date type.

"dates": [ { "type":"Publication", "dateString":"2012-01-01", "label": "Publication Date" }, { "type":"Repository Created", "dateString":"2012", "label":"Repository Created", } ]

spatial

Datatype: A spatial object
This is the spatial representation of the item.

spatial object

representationalPoint
Datatype: Array of Doubles
A collection of two points (saved as Doubles). The first value is latitude and must be within -180 & +180. The second value is the longitude and must be within -90 & 90.

boundingBox
Datatype: Object with 4 Double fields: minY, maxY, minX, maxX
The bounding box of an item. The maxY, minY, maxX, minX represent the four corners of the bounding box.

representationalPointIsDerived
Datatype: Boolean
Whether or not the representational point is derived. This is generally false.

"spatial": { "representationalPoint":[123,23], "representationalPointIsDerived":false, "boundingBox": { "maxY":23.22, "maxX":12.12, "minX":23.21, "minY":43 } }

facets (a.k.a. Extensions)

Facets are extensions built to help extend ScienceBase by creating specific fields for specific data. Each facet is an object in the collection of facets and must have the field "className" which defines the facet and thus what the objects other fields will be. The className is a string of the fully qualified class name in ScienceBase, eg. "className":"gov.sciencebase.catalog.item.facet.ProjectFacet". An important note: when adding facets to already existing items you must include all the previous facets (assuming you don't want to delete all of them).

"facets": [ {"className":"<fully qualified class name>", <other fields>...}, {"className":"<fully qualified class name>", <other fields>...} ]

extents

Datatype: Array of Integers
An array of extent numbers from Footprint Studio

files

Datatype: Array of file objects
These are the files associated with the item.

file Object

name
Datatype: String
The name of the file.

contentType
Datatype: String
The type of file. Eg. "application/json"

contentEncoding
Datatype: String
The encoding of the file.

pathOnDisk
Datatype: String
The path on disk of the file. This is a string which can be used to download individual files.

url
Datatype: URI
A URL link to download the file.

title
Datatype: String
The title of the file. This may be the file name.

size
Datatype: Long
The size of the file in bytes.

systemType
Datatype: String enum
Internal system type of the file.

uploadedBy
Datatype: String
The email of the person who uploaded the file.

dateUploaded
Datatype: DateTime
The date and time the file was uploaded.

processed
Datatype: Boolean
Whether the file has been processed by ScienceBase

processToken
Datatype: String
The token used when processing this file.

useForPreview
Datatype: Boolean
Whether to use the file as a preview image. Only available for images.

s3Object
Datatype: s3 Object
The s3 object with s3 download link and related information.

originalMetadata
Datatype: Boolean
Whether this is the original metadata of the item.

imageWidth
Datatype: Integer
The width of the file if the file is an image (null otherwise).

imageHeight
Datatype: Integer
The height of the file if the file is an image (null otherwise).

"files": [ { name: "55b7eb8fe4b09a3b01b6048b.json", title: "", contentType: "application/json", contentEncoding: null, pathOnDisk: "__disk__13/0f/35/130f35b5f6573233c7a20aea5d4533ec3b912068", processed: false, processToken: null, imageWidth: null, imageHeight: null, size: 15273, dateUploaded: "2015-11-09T19:04:40Z", uploadedBy: "rprescott@usgs.gov", originalMetadata: false, useForPreview: false, s3Object: null, url: "https://www.sciencebase.gov/catalog/file/get/5640edd5e4b0831b7d62e540?f…" } ]

permissions

Datatype: Object with two access control list objects: read & write
These are the permissions of an item. These should be managed inside ScienceBase

read
The read permissions of an item.

write
The write permissions of an item.

ACL Object

acl
Datatype: Array of Strings
Each value in this relates to a permission. These can be public like "PUBLIC", user based like "USER:abc@usgs.gov", or role based like "ROLE: ABCD".

inherited
Datatype: Boolean
Whether the permissions are inherited from another item or set directly on this item.

inheritsFromId
Datatype: String – limited to valid item ids
The id of the item the permissions are inherited from if inherited is true. Otherwise this field is omitted.

"permissions": { "read": { "acl":["PUBLIC"], "inherited":true, "inheritsFromId":"4f3559d2da0661d9ec041a09" }, "write": { "acl":["USER:abc@usgs.gov", "ROLE: ABCD"], "inherited":false } }

distributionLinks

Datatype: Array of distributionLink objects (non-editable)
These are automatically generated links providing access to data. Link types are "kml", "serviceCapabilitiesUrl", and "downloadLink"

"distributionLinks": [ { "uri": "https://www.sciencebase.gov/catalogMaps/mapping/ows/5640edd5e4b0831b7d6…", "title": "KML Service", "type": "kml", "typeLabel": "KML Download", "rel": "alternate", "name": "", "files": "" }, { "uri": "https://www.sciencebase.gov/catalogMaps/mapping/ows/5640edd5e4b0831b7d6…", "title": "ScienceBase WMS Service", "type": "serviceCapabilitiesUrl", "typeLabel": "OGC Service Capabilities URL", "rel": "alternate", "name": "", "files": "" }, { "uri": "https://www.sciencebase.gov/catalog/file/get/5640edd5e4b0831b7d62e540", "title": "Download Attached Files", "type": "downloadLink", "typeLabel": "Download Link", "rel": "alternate", "name": "itemwithallfiel.zip", "files": [ { "name": "55b7eb8fe4b09a3b01b6048b.json", "title": "", "contentType": "application/json", "size": 15273, "checksum": null } ] } ]

previewImage

Datatype: Object with 1 string field "from" and 4 image fields "thumbnail", "small", "medium", "large"

from
Datatype: String
Where the image is from. eg. "mapPreview", "webLinks"

thumbnail, small, medium, large
Datatype: Object with two fields: uri & title
Medium and large image sizes may be omitted if the image isn't large enough.

title
Datatype: String
The title of the image.

uri
Datatype: URI
The URI of the image.

locked

Datatype: Boolean
Whether the item is locked from editing.