Resources
Presentation Data for SOCH in version 0.99
This page describes the presentation block of SOCH object data, i.e. the basic summary information about objects. The presentation block is useful for applications which need to start using the SOCH API quickly. Applications that need more detailed information about the objects can use the full RDF data structure.
For the full SOCH protocol data structure, see protocol versions.
The presentation is only part of the SOCH data for an object. There are many search parameters that can be used, but that information is not necessarily part of the presentation. It is the content providers who decide what information to present. Application developers can use the SOCH API, see application development.
By using the RDF format and the semantic web, applications can access the full object information.
Elements in the Presentation Block
| Element | Description | Card |
| pres:item | Element to hold the object together | 1 |
| pres:version | Version of the protocol, e.g. 0.99 | 1 |
| pres:entityUri | The persistent URI for the object, e.g. http://kulturarvsdata.se/shm/object/1234 | 1 |
| pres:type | Object type | 1 |
| pres:id | Object identity | 1 |
| pres:idLabel | Label for identifying the object | 1 |
| pres:itemLabel | Main description of the object, e.g. classification or name | 1 |
| pres:tag | Keywords for the object | 0..n |
| pres:description | Description of the object | 1 |
| pres:content | Other contents in the form of running text that could be of interest for the user | 0..1 |
| pres:context | Collection of a context for the object consisting of <pres:event>, <pres:placeLabel>,<pres:timeLabel> and <pres:nameLabel> | 1..n |
| pres:event | An event | 0..1 |
| pres:placeLabel | A place for the event (if any) | 0..1 |
| pres:timeLabel | A time for the event (if any) | 0..1 |
| pres:nameLabel | A person or organization connected to the event (if any) | 0..1 |
| georss:where | Coordinates for the object in GeoRSS format, consisting of the element <gml:Point> | 0..1 |
| gml:Point | <gml:pos>Latitude Longitude</gml:pos> | 0..1 |
| pres:image | Collection of image information consisting of the elements below. | 0..n |
| pres:src type=”im_type” | Link to the image source, the attribute ”type” specifies the image type, e.g. ”jpg” | 1 |
| pres:byline | Text specifying photographer and organization | 1 |
| pres:motive | Description of the image motive | 0..1 |
| pres:copyright | Organization or person owning the copyright to the image | 1 |
| pres:mediaLicense | License regulating the use of the image | 1 |
| pres:mediaUri | SOCH URI for the image if it is a SOCH object of its own | 0..1 |
| pres:mediaUrl | HTML URL to the image | 1 |
| pres:references | Collection of links to other related objects, using<pres:reference> elements | 0..1 |
| pres:reference | Link to a related object | 1..n |
| pres:representations | Collection of representation formats for the object, currently consisting of three or four <pres:representation> elements | 1 |
| pres:representation format=”HTML” | The web page for the object in the source system | 1 |
| pres:representation format=”RDF” | Persistent URI for the object in RDF format | 1 |
| pres:representation format=”presentation” | The XML representation of the object, i.e. the<pres:item> described here | 1 |
| pres:representation format=”museumdat” | The Museumdat representation of the object, if any | 0..1 |
| pres:organization | The organization owning the object, e.g. ”Statens Historiska Museer”. Usually this is the content provider. | 1 |
| pres:organizationShort | Abbreviation of the organization name, e.g. ”shm” | 1 |
| pres:service | The service delivering the object, e.g. object (which usually implies that the data is fetched from an object database) | 1 |
| pres:dataQuality | Data quality can be raw (rådata) or processed (bearbetad) | 1 |
| pres:buildDate | The time when the information was fetched from the content provider | 1 |
SOCH Protocol Description – version 0.99
This page describes the protocol and elements used in SOCH. For the latest version of the protocol in RDF format, see protocol versions.
Application Developers who want to exploit SOCH can use the SOCH API or a standard SRU API. The search parameters are described below. Searchable parameters are marked with an ”S”. For information on how to use the APIs, see Application Development.
Note regarding natural languages: The element values are in Swedish by default. Values in other languages are entered according to the suffix principle @eng for English, etc. The text strings are finished by the ”at” character followed by the three letter language code according to ISO 639-2
(alpha-3). Example: <itemTitle>aéroplane@fre</itemTitle>
Elements or Parameters? Some hints on the vocabulary used:
- ”Elements” refer to the information fields delivered by the content providers.
- ”Parameters” refer to the information pieces visible (and often searchable) from the applications using SOCH.
- Often elements correspond to parameters with the same name.
Table of Contents
Elements and Resources in Alphabetical Order
addedToIndexDate
boundingBox
buildDate
cadastralUnit
collection
containsInformationAbout
containsObject
context
contextLabel
contextType
continentName
coordinates
country
countryName
county
countyName
createdDate
dataQuality
Entity
eventAuth
eventName
firstName
fromPeriodId
fromPeriodName
fromTime
fullName
gender
geoDataExists
hasBeenUsedIn
hasChild
hasFind
hasImage
hasObjectExample
hasParent
hasPart
image
isDescribedBy
isFoundIn
isPartOf
isRelatedTo
isVisualizedBy
itemClass
itemClassName
itemColor
itemDescription
itemForIndexing
itemKeyWord
itemLabel
itemLicense
itemLicenseUrl
itemMaterial
itemMeasurement
itemMotiveWord
itemName
itemNumber
itemSpecification
itemStyle
itemTechnique
itemTitle
itemType
ksamsokVersion
lastChangedDate
mediaType
municipality
municipalityName
museumdatUrl
name
nameAuth
nameId
organization
owl:sameAs
parish
parishName
periodAuth
placeName
placeTermAuth
placeTermId
pointDistance
presentation
province
provinceName
sameAs
serviceName
serviceOrganization
subject
surname
theme
thumbnail
thumbnailExists
timeInfoExists
timeText
title
toPeriodId
toPeriodName
toTime
url
visualizes
Search Parameters for Application Developers
End users as well as applications using SOCH can exploit the parameters marked with ”S” in the tables below to search for objects. There are also some free text search options available through the following parameters:
- text (free text search in almost all elements)
- item (free text search in elements with central object information)
- time (free text search in elements specifying time and events)
- place (free text search in elements specifying places)
- actor (free text search in elements specifying people or organizations)
Free text search is carried out for the elements marked with ”Fr” in the tables below. ”Tx” means that only the most general free text search apply.
Entity (Object) Parameters
An entity is a searchable object in SOCH. It could be an ancient object, a cultural environment, a piece of art, a photograph, a book, or anything else that a content provider in a cultural heritage institution chooses to deliver. An entity is implemented as an RDF resource with a persistent URI in the format domain/institution/service/id, e.g. http://kulturarvsdata.se/raa/fmis/12345. The first table below lists the general elements for an entity.
NOTE: The elements that are fetched from content providers and correspond directly to search parameters with the same name that can be used in applications are marked with ”S”. Elements marked with ”Fr” are used in free text searches, while ”Tx” means that the elements are only used in the most general free text search.
| ksamsokVersion | The version of the SOCH protocol that this entity fulfils | 1 | ||
| buildDate | The time when the object information was generated and delivered to SOCH. Format: YYYY-MM-DD (e.g. 2008-09-15) according to ISO 8601 | 1 | ||
| addedToIndexDate | The time when the object information was first available in SOCH. Format: YYYY-MM-DD (e.g. 2008-09-15) according to ISO 8601. The element is generated automatically and must not be delivered by the content provider | 0 | S | |
| serviceName | The name of the service (often database) that the data is delivered from, e.g. ”object” for an object oriented database or ”media” for pictures. The name must contain alphanumeric characters, but hyphens and underscores are also valid | 1 | S | Tx |
| serviceOrganization | The institution delivering the service, e.g. ”SHM” or ”RAÄ”. The name must contain alphanumeric characters, but hyphens and underscores are also valid | 1 | S | Tx |
| itemForIndexing | This is a special parameter that should normally not be used. For objects that should not be indexed, the element is set to ”n” | 0..1 | ||
| collection | If the object belongs to a collection (e.g. a museum collection), then the name is specified here | 0..n | S | |
| theme | Theme for the object. Themes can be used across institutions. There could be short-term themes like an anniversary for an inventor or long-term themes like ”material suitable for early school years”. Themes can be defined locally or globally in http://kulturarvsdata.se/resurser/Theme | 0..n | S | |
| createdDate | The time when the object was first created in the source database. Format: YYYY-MM-DD (e.g. 2008-09-15) according to ISO 8601 | 0..1 | ||
| lastChangedDate | The date of the latest change of the object in the source database. The element is needed for incremental harvest of data to work. If the element is missing, the central repository is updated through a total service re-harvest. Format: YYYY-MM-DD (e.g. 2008-09-15) according to ISO 8601 | 0..1 | S | |
| url | URL to the original web site for the object at the content provider (HTML) | 1 | ||
| museumdatUrl | URL to the Museumdat representation of the object, if any | 0..1 | ||
| thumbnail | URL to a selected thumbnail of the object. The thumbnail is not harvested, but resides at the content provider | 0..1 | ||
| thumbnailExists | This is a help index for searching objects with image representation (thumbnailExists=”j”). The element is generated automatically and must not be delivered by the content provider | 0 | S | |
| subject | Subject specification, e.g. ”Archaeology”. For a list of available subjects, see: http://kulturarvsdata.se/resurser/Subject | 0..n | S | |
| mediaType | Media type according to MIME (type/sub type), e.g. ”image/gif”. For a list of available media types, see: http://www.iana.org/assignments/media-types/ | 0..n | S | |
| dataQuality | The data quality can be ”raw” or ”processed”. Processed means that the information has been adopted for a broader audience. For a list of available values, see: http://kulturarvsdata.se/resurser/DataQuality | 1 | S | |
| itemType | This is the type of object, e.g. ”photo”. For a list of available item types, see: http://kulturarvsdata.se/resurser/EntityType | 1 | S | Fr |
| itemClass | Classification or categorization of the object. If there is a classification resource, this element is used. A classification or categorization is a finite, defined list of values, e.g. ”itemClass=[itemAuth]#Redskap” | 0..n | S | |
| itemClassName | Class or category in plain text if there is no classification resource | 0..n | S | Fr |
| itemId | Deprecated | 0 | ||
| itemName | The main object name, e.g. itemName=”Yxa” (Axe) | 1..n | S | Fr |
| itemLabel | Duplication of pres:itemLabel for sorting of objects to work in applications | 1 | S | |
| itemSpecification | Model specification or the like, e.g. ItemSpecification=”Eneggad” | 0..n | S | Fr |
| itemTitle | Title or popular name for the object, e.g. itemTitle=”Alundaälgen” | 0..n | S | Fr |
| itemDescription | Free text descriptions used in free text searching | 0..n | Fr | |
| itemKeyWord | Keywords | 0..n | S | Fr |
| itemMotiveWord | Description words for the motive of a photo or a piece of art, e.g. itemMotiveWord=”djur” (animal) | 0..n | S | Fr |
| itemMaterial | Material that the object is made of, e.g. ”sten” (stone) | 0..n | S | Fr |
| itemTechnique | Technique used to produce the object, e.g. ”sharpened” | 0..n | S | Fr |
| itemStyle | Style for the object, e.g. ”Gustaviansk” | 0..n | S | Fr |
| itemColor | Colour of the object, e.g. ”Blå” (Blue) | 0..n | S | Fr |
| itemNumber | Inventory/accession number, or other (often internal) number | 0..n | S | |
| itemMeasurement | Measurements for the object | 0..n | ||
| itemLicense | License for the object (not related images): http://kulturarvsdata.se/resurser/License#[spec] | 1 | S | |
| itemLicenseUrl | Specific version of the license: http://creativecommons.org/licenses/[spec]/2.5/se/ | 1 | S | |
| context | A context or event that is linked to the object, see Time, Place, Actor | 0..n | ||
| isRelatedTo | URI to a related object, e.g. a relation between an object and a painting of the object. Try not to use this default relation type. Select one of the predefined relation types at http://www.ksamsok.se/in-english/resources/#relation | 0..n | ||
| image | This is a link to a picture that constitutes the object. It can also be a picture that shows the object without being a SOCH object itself. See Image. Note that the element imageMotiveWord is indexed and searchable | 0..n | ||
| presentation | This is the summary presentation block, which is an XML format block that is not indexed, see presentation format. This is a subset of the RDF data, used for easier presentation in an application | 1 |
Time Parameters
The time related elements and parameters are connected to the object through a specific event or content, e.g. ”create”. There can be several contents for an object. Below is a description of the time parameters.
| contextType | Contexts are available for time, place and actor. For a list of valid contexts, see http://kulturarvsdata.se/resurser/ContextType | 1 | S | |
| contextLabel | A more specific description of the context | 0..1 | ||
| fromTime | Time or start of a time interval. Searches should be made per context type, to function properly. See example 6 here: Application Development | 0..1 | S | Fr |
| toTime | Time or end of a time interval. Searches should be made per context type, to function properly. See example 6 here: Application Development | 0..1 | S | Fr |
| timeInfoExists | This is a help index for searching objects with time information in either fromTime or toTime (timeInfoExists=”j”). The element is generated automatically and must not be delivered by the content provider | 0 | S | |
| fromPeriodName | Time or start of a time interval, expressed as a period name | 0..1 | S | Fr |
| toPeriodName | Time or end of a time interval, expressed as a period name | 0..1 | S | Fr |
| fromPeriodId | Time or start of a time interval, expressed as a period name code. Use this parameter or fromPeriodName | 0..1 | S | |
| toPeriodId | Time or end of a time interval, expressed as a period name code. Use this parameter or toPeriodName | 0..1 | S | |
| periodAuth | Authority for time period vocabulary, preferably SHM’s definitions. The parameter is used together with fromPeriodId and toPeriodId | 0..1 | S | |
| eventName | Name of an event connected to the object in this context | 0..1 | S | Fr |
| eventAuth | Authority for events. This parameter is used together with eventName | 0..1 | S | |
| timeText | Other unstructured time information | 0..1 |
Place Parameters
The place related elements and parameters are connected to the object through a specific event or content, e.g. ”find”. There can be several contents for an object. Below is a description of the place parameters.
| contextType | See contextType for Time | |||
| contextLabel | A more specific description of the context | 0..1 | ||
| continentName | Continent name | 0..1 | S | |
| country | Country code | 0..1 | S | |
| county | geoF:county County code (Länskod) | 0..1 | S | |
| province | geoF:province Province code (Landskapskod) | 0..1 | S | |
| municipality | geoF:municipality Municipality code (Kommunkod) | 0..1 | S | |
| parish | geoF:parish Parish code (Sockenkod) | 0..1 | S | |
| countryName | Country name | 0..1 | S | |
| countyName | geoF:county County name (Länsnamn) | 0..1 | S | Fr |
| provinceName | geoF:province Province name (Landskapsnamn) | 0..1 | S | Fr |
| municipalityName | geoF:municipality Municipality name (Kommunnamn) | 0..1 | S | Fr |
| parishName | geoF:parish Parish name (Sockennamn) | 0..1 | S | Fr |
| placeName | Other unstructured place information, including other languages | 0..n | Fr | |
| cadastralUnit | Cadastral unit (Fastighetsbeteckning). Municipality is needed for the same context | 0..1 | S | |
| placeTermId | Place ID with an authority | 0..1 | S | |
| placeTermAuth | Authority for the placeTermId | 0..1 | S | |
| coordinates | Coordinates according to WGS84, RT90 or SWEREF99. The corresponding search parameter is either a rectangle or a circle,i.e. a geographical area, specified on a map, for which the search is carried out | 0..1 | ||
| geoDataExists | This is a help index for searching objects with coordinates (geoDataExists=”j”). The element is generated automatically and must not be delivered by the content provider | 0 | S | |
| boundingBox | A geographical rectangle (e.g. marked on a map) within which an application carries out a search. More information | 0 | S | |
| pointDistance | A geographical circle (e.g. marked on a map) within which an application carries out a search. More information | 0 | S |
People/Organization Parameters
The actor related elements and parameters are connected to the object through a specific event or content, e.g. ”reproduced”. There can be several contents for an object. Below is a description of the actor parameters.
| contextType | See contextType for Time. | |||
| contextLabel | A more specific description of the context. | 0..1 | ||
| firstName | foaf:firstName First name | 0..1 | S | Fr |
| surname | foaf:surname Surname (Last name) | 0..1 | S | Fr |
| fullName | foaf:fullName Firstname+space+Surname | 0..1 | S | Fr |
| name | foaf:name Unstructured name information used in free text search. | 0..1 | Fr | |
| organization | foaf:organization Organization name. If a person name is also provided in the above elements, this implies that the person belongs to the organization. | 0..1 | S | Fr |
| title | foaf:title Title of the person, see http://kulturarvsdata.se/resurser/Title | 0..1 | S | |
| gender | foaf:gender Woman (”K”) or Man (”M”) | 0..1 | S | Fr |
| nameId | Authorized ID for a person. | 0..1 | S | |
| nameAuth | Authority for person names, preferably from the National Library of Sweden. This parameter is used together with nameId. | 0..1 | S |
Relational Parameters
| isRelatedTo | URI to a related object. Avoid this default relationship type if possible. Select one of the predefined relationship types at http://www.ksamsok.se/in-english/resources/#relation | 0..n | ||
| containsInformationAbout | Main object contains information about the referred object | 0..n | ||
| containsObject | Main object contains the referred object | 0..n | ||
| isPartOf | Main object is a part of the referred object. This is an inverse relationship type of containsObject | 0..n | ||
| isFoundIn | Main object is found in the referred object. This is a specialization of the isPartOf relationship type | 0..n | ||
| hasBeenUsedIn | Main object has been used in the referred object | 0..n | ||
| hasChild | Main object is parent (superior) of referred object | 0..n | ||
| hasParent | Main object is child (subordinate) of referred object | 0..n | ||
| hasFind | Main object is a place that has a find (referred object) | 0..n | ||
| hasImage | Main object has an image (referred object) that shows more than the main object or is photographed from the main object, e.g. from a church | 0..n | ||
| hasObjectExample | Main object is a place which has a set of referred objects that presents the place in a descriptive manner | 0..n | ||
| hasPart | Main object consists of referred object (essential parts of a whole) | 0..n | ||
| isDescribedBy | Main object is described by the referred object, e.g. a literature reference | 0..n | ||
| visualizes | Used for the object type of ”object image” (”Objektavbildning”) | 0..n | ||
| isVisualizedBy | Inverse of the relationship type ”visualizes” | 0..n | ||
| owl:sameAs | Use this RDF standard relationship type if the object has more than one RDF representation | 0..n |
Other Resources (detailed parameters)
Some of the elements above are further specialised according to the following:
ItemNumber
ItemNumber contains the following sub-elements:
<number>Number</number>
ItemName
ItemName contains the following sub-elements:
<name>Label describing the object</name>
ItemSpecification
ItemSpecification contains the following sub-elements:
<spec>Model specification or the like</spec>
ItemMaterial
ItemMaterial contains the following sub-elements:
<material>Material, e.g. ”sten” (stone)</material>
ItemDescription
ItemDescription contains the following sub-elements:
<desc>Description</desc>
ItemMeasurement
ItemMeasurement contains the following sub-elements:
<value>Value, e.g. ”23”</value>
<unit>Unit, e.g. ”mm”</unit>
<qualifier>Specification of what the measurement means, e.g. ”egg” or ”förekonservering” (before preservation)</qualifier>
Image
Note that mediaMotiveWord is indexed (and therefore searchable) in SOCH Image consists of the following elements:
<lowresSource>Link to image source</lowresSource>
<highresSource>Link to imagesource</highresSource>
<byline>Byline consisting of photographer andorganization</byline>
<mediaMotiveWord>Motive word</mediaMotiveWord>
<mediaMotiveWord>Moremotive words</mediaMotiveWord>
<copyright>Organization/Person who owns theimage</copyright>
<mediaLicense rdf:resource=”http://kulturarvsdata.se/resurser/License#[spec]”/><mediaLicenseUrl rdf:resource=”http://creativecommons.org/licenses/[spec]/2.5/se”/>
Relation Types in SOCH
The term ”Relation Types” refer to relational links between SOCH objects. On a technical level this corresponds to the properties binding the objects together on the semantic web.
The following relation types are available in SOCH:
- containsInformationAbout
- containsObject
- hasBeenUsedIn
- hasChild
- hasFind
- hasImage
- hasObjectExample
- hasParent
- hasPart
- isDescribedBy
- isFoundIn
- isPartOf
- isRelatedTo (default value for relations)
- isVisualizedBy
- owl:sameAs
- sameAs (use ”owl:sameAs”)
- visualizes