The following documentation describes the ScienceBase Item core elements, how those elements are related to applicable metadata standards, some notes on how the elements are used in ScienceBase, and lists the sbJSON syntax used to house the items natively in ScienceBase. The sbJSON syntax is further transformed into various forms of XML and other outputs to support numerous interactions with ScienceBase.
The ScienceBase Item core model is continuing to be refined over time as we work to bring alignment across additional standards informing the development of ScienceBase. The sbJSON syntax will be changed over time as these refinements continue, and we will try to keep notes on this evolution here up to date.
To view the full JSON for a ScienceBase item, click here.
To view additional information you can have on ScienceBase items through Extensions, click here.
The Fields
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 for some types of items such as citations harvested from a publication source are simply the full title of the item. Some titles, such as a title for a particular rock core in a large collection, may be constructed from various information about the item to build a readable and meaningful title.
Titles are used as the item page's title so titles can show up in search results like Google.
"title":"Item Title"
Applicable Metadata Standards
- Dublin Core Metadata Element Set - http://purl.org/dc/elements/1.1/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" ]
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>"
Applicable Metadata Standards
- Dublin Core Metadata Element Set - http://purl.org/dc/elements/1.1/identifier
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"
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"
citation
Datatype: String
The citation that can be used to reference the item.
"citation": "Jay Diffendorfer, Roger Compton, Louisa Kramer, Zach Ancona, and Donna Norton, 2015-05, Onshore Industrial Wind Turbine Locations for the United States to March 2014: United States Geological Survey (USGS): Denver, CO, http://pubs.usgs.gov/ds/817/downloads/USGSWind_Turbine_03_2014.zip, http://dx.doi.org/10.3133/ds817, http://eerscmap.usgs.gov/windfarm/."
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 (Wikipedia article). 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" } ]
Applicable Metadata Standards
- Dublin Core Metadata Element Set - http://purl.org/dc/elements/1.1/identifier
link
Datatype: Hashmap (non-editable)
This 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>" } }
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.
Early iterations of ScienceBase used the Provenance field for harvesting operations to contain a statement about how and when an item was harvested. Current work in ScienceBase will replace this practice with referenced information about harvesting operations stored elsewhere, leaving the Provenance field for either direct user input through the form or housing of detailed provenance information pulled from an applicable metadata standard in an item harvested into ScienceBase.
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 it is, eg. 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.
We plan to add more advanced contacts adding and matching to ScienceBase in the future.
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.gif", smallLogoUrl: "http://my.usgs.gov/static-cache/images/dataOwner/v1/logosSmall/USGSLogo.gif", 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" } } } ]
webLinks
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" ]
tags
Datatype: Array of tag Objects
The user specified tags or keywords of an item. These are used for grouping and searching items. It is a collection of tag objects, and the simplest representation of a tag has just one field, "name", the name the of the tag. Tags may also be terms from a vocabulary, with a type and scheme in addition to just the name.
tag Object
name
Datatype: String
The tag value.
scheme
Datatype: URI
Indicates what vocabulary the term came from. The scheme is a resolvable URI when applicable similar the scheme in ATOM categories.
type
Datatype: String
Classifies the usage of the tag such as "Stratum", "Theme", "Label".
"tags": [ { "name":"Tag1" }, { "name":"Tag2" }, { "type":"Theme", "scheme":"http://uri/to/vocab", "name":"Happy Topic" } ]
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>...} ]
files
Datatype: Array of file Objects
These are the files associated with the item. Generally you should avoid putting files larger than 100MB inside ScienceBase. See Uploading Files with Groovy on how to RESTfully upload files into ScienceBase.
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=__disk__13%2F0f%2F35%2F130f35b5f6573233c7a20aea5d4533ec3b912068" } ]
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 } }
extents
Datatype: Array of Integers
An array of extent numbers from Footprint Studio
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.