ScienceBase Item Core Model

The ScienceBase Item core is based on the Dublin Core Metadata Element Set but also includes other elements that may or may not be associated with other metadata standards that are useful for the core attribution of ScienceBase items. It is used as a means to integrate across multiple metadata standards, conventions, and practices in describing a wide array of scientific data and information assets important to science teams using ScienceBase.

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"
]

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 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.

Child pages

ScienceBase Item Core Model

The Fields

title

subTitle

alternateTitles

id

body

summary

citation

identifiers

identifier Object

link

purpose

rights

provenance

provenance Object

materialRequestInstructions

hasChildren

parentId

contacts

contact Object

webLinks

weblink Object

browseCategories

browseTypes

systemTypes

tags

tag Object

dates

date Object

spatial

spatial Object

facets (a.k.a. Extensions)

files

file Object

permissions

read

write

ACL Object

extents

previewImage

locked