Protokoll och parametrar

Leveransprotokoll för K-samsök version 1.1

Uppdaterad 2022-06-29

Den här sidan beskriver protokoll och element som används i K-samsök. Senaste versionen av protokollet i RDF-format hittar du här: protokollversioner.

K-samsök som OWL.

Kommande ändringar på K-samsöks API och protokoll utlysas här.

Tillämpningsutvecklare (TU) som vill nyttja K-samsök använder ett specialskrivet API för detta. Sökparametrarna beskrivs längre ner på den här sidan. Element som motsvaras av sökparametrar är markerade med ”S”. Hur man använder API:et mot parametrarna och hur resultatsidan ser ut beskrivs här.

Naturliga språk: Värden för elementen antas vara på svenska om inget annat anges, men vi uppmanar leverantörer att även markera text på svenska om det är möjligt. Värden på språk anges i XML-element enligt principen xml:lang="en" för engelska osv. Textsträngar ska markeras med språkförkortningen enligt ISO 639-1 (tvåbokstavskoder). Exempel: <itemTitle xml:lang="fr">aéroplane</itemTitle>

Element och resurser i bokstavsordning

Sökparametrar för tillämpningsutvecklare (TU)

De tillämpningar som använder K-samsök för att söka efter kulturarvsdata kan utnyttja de parametrar som är markerade med ”S” i tabellerna längre ner på den här sidan. Dessutom finns några fritextmöjligheter att tillgå via följande parametrar:

  • text (fritextsökning som söker i alla parametrar)
  • strict (som text ovan men utan ordböjningar)
  • item (fritextsökning som söker i alla objekt- och föremålsorienterade parametrar)
  • time (fritextsökning som söker i alla tids- och händelseorienterade parametrar)
  • place (fritextsökning som söker i alla platsorienterade parametrar)
  • actor (fritextsökning som söker i alla person-, företags- och organisationsorienterade parametrar)

Fritextsökningar sker i de parametrar som markerats med ”Fri” i tabellerna.

Kardinalitet

Tredje kolumnen i tabellerna avser attributets kardinalitet (dvs hur många värden får förekomma). Obs att kardinalitet var minsta värde är ”1” är obligatoriska.

Entitet

En entitet är ett sökbart objekt i K-samsök. Det kan vara ett utgrävt föremål, ett konstverk, en bild, en bok, en händelse eller annat som en producent i ABM-sektorn levererar till K-samsök. En entititet implementeras som en RDF-resurs med persistent URI på formatet domän/institution/tjänst/id, t ex http://kulturarvsdata.se/raa/fmi/12000000112658. Följande element är egenskaper för resursen Entity. Obs: De element som motsvaras av sökparametrar som tillämpningsutvecklare (TU) kan ange markeras med ett ”S” näst längst till höger. Element markerade med ”Fri” används vid fritextsökningar, medan ”Tx” betyder endast högsta nivån av fritextsökning.

ksamsokVersion Version av K-samsöksprotokollet 1
buildDate Tid när objektinformationen genererades. Format: YYYY-MM-DD (exempel: 2008-09-15) enligt ISO 8601 1
addedToIndexDate Tid när objektinformationen först blev tillgänglig i K-samsök. Format: YYYY-MM-DD (exempel: 2008-09-15) enligt ISO 8601. Detta element skapas automatiskt av K-samsök centralt och ska inte levereras in. 0 S
serviceName Namn på tjänsten som data levereras från, t ex object om det är en föremålsdatabas eller media om det är bilder. Namnet kan väljas fritt. 1 S Tx
serviceOrganization Institutionen som levererar tjänsten, t ex SHM eller RAÄ. Ska vara en förkortning. 1 S Tx
itemForIndexing Specialparameter som används mycket sällan. Sätt värdet n om objektet inte ska indexeras. 0..1
text Fritextparameter som söker i alla fält inklusive ordens böjningar. 0 S
strict Fritextparameter som söker i alla fält men utan böjningar av orden. 0 S
item Fritextparameter som söker i alla föremålsrelaterade fält. 0 S
collection Namn på samlingen som objektet tillhör 0..n S
theme Tema för objektet. Teman kan användas som urval tvärs över institutionerna. Det kan vara kortsiktiga teman som ett jubileumsår för en uppfinnare eller långsiktiga teman som ”material lämpligt för skolans tidiga årskurser”. Teman kan definieras lokalt men även globalt: http://kulturarvsdata.se/resurser/Theme
Deprecated.		 0..n S
createdDate Datum då objektet skapades i databasen. Format: YYYY-MM-DD (exempel: 2008-09-15) enligt ISO 8601. 0..1
lastChangedDate Datum då objektet senast ändrades i databasen. Fältet är nödvändigt för att dataskördningen ska fungera. Saknas detta element får man skörda om hela databasen vid uppdateringar. Format: YYYY-MM-DD (exempel: 2008-09-15) enligt ISO 8601. 0..1 S
url URL till objektets hemsida hos den lokala producenten (HTML) 1
museumdatUrl URL till museumdat-representationen av objektet
Deprecated.		 0..1
thumbnail URL till den av objektets tumnaglar hos den lokala producenten som valts ut att representera objektet 0..1
thumbnailExists Index för att söka fram objekt med enbart bildrepresenation, mha thumbnailExists="j". Detta element skapas automatiskt av K-samsök centralt och ska inte levereras in. 0 S
subject Ämnesavgränsning, t ex "Arkeologi". Om inga ämnen finns angivna så träffas objektet av alla sökningar oavsett ämnesavgränsning i sökningen. Listan på ämnen hittar du här: http://kulturarvsdata.se/resurser/Subject 0..n S
media Länk till media som inte har en egen URI. Se Media. Observera att elementet mediaMotiveWord indexeras. 0..n
mediaType Avgränsning av mediatyper enligt MIME (typ/subtyp), t ex "image/gif". Om inga mediatyper finns angivna så träffas objektet av alla sökningar oavsett avgränsning i sökningen. Listan på mediatyper hittar du här: http://www.iana.org/assignments/media-types/ 0..n S
dataQuality Beskrivningsnivå, "Rådata" eller "Bearbetad". Med bearbetade data avses sådana data som anpassats särskilt för en bred publik. Listan hittar du här: http://kulturarvsdata.se/resurser/DataQuality 1 S
itemSuperType Övergripande typ (fr o m version 1.1) som är obligatorisk. Listan på superobjekttyper hittar du här: http://kulturarvsdata.se/resurser/EntitySuperType 1 S Fri
itemType Typ av objekt, t ex "Föremål". Listan på objekttyper hittar du här: http://kulturarvsdata.se/resurser/EntityType. Ett dataset/tjänst kan innehålla flera olika typer av itemType. 1 S Fri
itemClass Objektets klass, kategorisering eller klassifikation. Om det finns en klassificeringsresurs så används det här elementet. En klass eller kategorisering är en ändlig, definierad lista av värden. Exempel: itemClass=[itemAuth]#Redskap. 0..n S
itemClassName Klass eller kategori, om det inte finns en klassificeringsresurs 0..n S Fri
itemId Deprecated. 0
itemName Objektets huvudsakliga benämning eller sakord. Specifik benämning av ett objekt, t ex itemName="Yxa". Se ItemName. 1..n S Fri
itemLabel Duplicering av pres:itemLabel för att sortering av objekt ska fungera bra 1 S
itemSpecification Modellbeteckning eller liknande, t ex ItemSpecification="Eneggad". Se ItemSpecification. 0..n S Fri
itemTitle Titel eller verksnamn, t ex itemTitle="Alundaälgen" eller itemTitle="Bredarör" 0..n S Fri
itemDescription Fritextbeskrivningar som används vid generella sökningar. Se ItemDescription. 0..n Fri
itemKeyWord Nyckelord 0..n S Fri
itemMotiveWord Ord som förekommer som beskrivning av ett motiv i ett bild- eller målningsobjekt t ex itemMotiveWord="djur" 0..n S Fri
itemMaterial Material som objektet består av, t ex "sten". Se ItemMaterial. 0..n S Fri
itemTechnique Teknik för att producera objektet, t ex "slipad" 0..n S Fri
itemStyle Stil som präglar objektet, t ex "Gustaviansk" 0..n S Fri
itemColor Färg som präglar objektet, t ex "Blå" 0..n S Fri
itemNumber Inventarienummer eller annan identifikation av objektet. Se ItemNumber. 0..n S
itemMeasurement Mått och mätvärden för objektet, se ItemMeasurement 0..n
itemLicense Licens för objektet (ej tillhörande eller relaterade bilder): http://kulturarvsdata.se/resurser/License#[spec] 1 S
itemLicenseUrl Specifik version av licensen: http://creativecommons.org/licenses/[spec]/2.5/se/ 1 S
itemMark Ska ungefär motsvara CIDOC-CRMs P65 shows visual item: symboler, ornamentik och andra visuella tecken och märken på ett fysiskt objekt. Se ItemMark 0..n
itemInscription Ska ungefär motsvara CIDOC-CRMs P128 carries: inskrivna korta texter på ett fysiskt objekt. Se ItemInscription 0..n
context Ett sammanhang som kan kopplas till objektet. Se Tider, Platser, Personer/Organisationer. 0..n
isRelatedTo URI till relaterat objekt, t ex en koppling mellan ett föremål och en fyndplats. Undvik denna default-relation om möjligt. Välj bland de fördefinierade relationstyperna 0..n
image Länk till bild som inte har en egen URI. Se Image. Observera att elementet imageMotiveWord indexeras. 0..n
presentation Listformatet att presentera för tillämpningsutvecklare (TU), se presentationsformat. Det är strukturen inom elementet <presentation> som levereras från K-samsök. 1

Kontext

Kontext är sammanhang som kopplas till ett objekt, t ex tid, plats eller person (t ex far eller mor till). Kontext anges som med en övergripande parameter (contextSuperType), en mer specifik (contextType) samt contextLabel som anger ett värde (se tabell nedan).

ContextSuperType ContextType ContextLabel Roller
1000.Skapa (create) 1100.Designa (skapa förutsättningar för att något ska bli till) Formge, Skissa, Uppfinna, Beställa, Komponera, Rita, Konstruera, Skapa förstudie Beställare, Kompositör, Författare, Arkitekt, Uppfinnare, Scenograf, Formgivare, Konstruktör, Producent, Arrangör, Regissör. Producenter av immateriellt kulturarv.
1200.Producera (att skapa någonting konkret) Tillverka, Färdigställa, Modifiera, Fotografera Fotograf, Målare, Byggare, Byggmästare, Byggherre, Gravör, Myntmästare, Konstnär, Snickare, Murare, Tekniker, Förläggare, Publicist,
Musiker, Skådespelare, Tryckare, Påskrift av, Producent. (Vid osäkerhet: Tillverkare) Produktion av materiellt kulturarv.
1300.Starta (Event) Utspela sig (Agenter) Födas,
2000.Interagera (interact) 2100.Hitta Hitta, Påträffa Upphittare
2200.Överföra Överföra, ge/skänka, förvärva, deponera, accedera, röva (krigsbyte), tappa, deponera (i marken), försvinna Förvärvare, Förmedlare, Köpare, Säljare, Generalagent, Givare, Deponent, Återförsäljare, (Roll för krigsbyte?)
2300.Undersöka och beforska Undersöka, inventera, konditionsbeskriva, gräva, konservera, analysera, dokumentera, samla in, Inventerare, Grävare, Undersökare, Konservator, Arkivbildare, Intervjuare, Upptecknare, Informant
2400.Äga Äga, förvalta, äga immateriellt Ägare, Upphovsrättsinnehavare, Patentinnehavare
2500.Använda Bruka/nyttja/använda, bo Brukare
2600.Reproducera Avbilda, rita av/måla av, fotografera av eller reprofotografera Fotograf, Skanneroperatör, Bildredaktör, Konstnär
2700.Visa (Fysiskt ting och Event)Visa upp, Ställa ut, Publicera
2800.Verka (Agenter) Regera, Vara anställd, Ta ett uppdrag, Vara gift Uppdragsgivare, Arbetsgivare, Beställare, Gift med
3000.Upphöra (cease) 3100.Avföra Förstöra, gallra, kassera
3200.Avsluta (Event) Utspela sig (Agenter) Dö, Lägga ner

Tider

Elementen för tid beskriver ett visst sammanhang för entiteten, t ex "Tillverkad". Det kan finnas flera sådana sammanhang definierade för en entitet. Följande element är tidsrelaterade egenskaper för ett Context.

contextSuperType Övergripande Sammanhang/kontext enligt ändlig lista (överordnad contextType). Sammanhanget gäller för tider, platser och personer/organisationer. Listan på sammanhang hittar du här: http://kulturarvsdata.se/resurser/ContextSuperType 1 S
contextType Sammanhang/kontext enligt ändlig lista/rdf-resurs. Sammanhanget gäller för tider, platser och personer/organisationer. Listan på sammanhang hittar du här: http://kulturarvsdata.se/resurser/ContextType 1 S
time Fritextparameter som söker i alla tids- och händelserelaterade fält. 0 S
contextLabel Specificerar det som står i contextType, kan vara en hänvisning till en rdf-resurs eller fritext. 0..1
fromTime Tidpunkt eller start på tidsintervall. Sökningar bör ske per kontexttyp, se exempel 6 här 0..1 S Fri
toTime Tidpunkt eller slut på tidsintervall. Anges tillsammans med fromTime. Sökningar bör ske per kontexttyp, se exempel 6 här. 0..1 S Fri
timeInfoExists Index för att söka fram objekt som har tidsangivelser i fromTime eller toTime, mha timeInfoExists="j". Detta element skapas automatiskt av K-samsök centralt och ska inte levereras in. 0 S
fromPeriodName Tidpunkt eller start på tidsintervall. 0..1 S Fri
toPeriodName Tidpunkt eller slut på tidsintervall. Används tillsammans med fromPeriodName. 0..1 S Fri
fromPeriod Tidpunkt eller start på tidsintervall, i form av URI för perioden. 0..n S
toPeriod Tidpunkt eller slut på tidsintervall, i form av URI för perioden. 0..n S
fromPeriodId Tidpunkt eller start på tidsintervall (kod). Detta är ett alternativ till fromPeriodName. Utgår – använd fromPeriod istället. 0..1 S
toPeriodId Tidpunkt eller slut på tidsintervall (kod). Detta är ett alternativ till toPeriodName. Utgår – använd toPeriod istället. 0..1 S
periodAuth Auktoritet för perioder, t ex SHM. Används tillsammans med fromPeriodId och toPeriodId. Utgår – använd fromPeriod och toPeriod istället. 0..1 S
eventName Namn på en händelse. 0..1 S Fri
event Auktoritet för händelser, i form av URI. 0..n S
eventAuth Auktoritet för händelser. Anges tillsammans med eventName. Utgår – använd event istället. 0..1 S
timeText Annan tidsuppgift, ostrukturerade data 0..1

Platser

Elementen för platser beskriver ett visst sammanhang för entiteten, t ex "Upphittad". Det kan finnas flera sådana sammanhang definierade för en entitet. Följande element är platsrelaterade egenskaper för ett Context.

contextType Se contextType för Tider.
place Fritextparameter som söker i alla platsrelaterade fält. 0 S
contextLabel Specificerar det som står i contextType, kan vara en hänvisning till en rdf-resurs eller fritext. 0..1
continentName Kontinent 0..1 S
country Land 0..1 S
county geoF:county Länskod 0..1 S
province geoF:province Landskapskod 0..1 S
municipality geoF:municipality Kommunkod 0..1 S
parish geoF:parish Sockenkod 0..1 S
countryName Landsnamn 0..1 S
countyName geoF:county Länsnamn 0..1 S Fri
provinceName geoF:province Landskapsnamn 0..1 S Fri
municipalityName geoF:municipality Kommunnamn 0..1 S Fri
parishName geoF:parish Sockennamn 0..1 S Fri
placeName Annat platsnamn, t ex på andra språk 0..n Fri
cadastralUnit Fastighetsbeteckning. Kräver att kommun anges för samma context. 0..1 S
placeTerm Plats-ID hos auktoritet, i form av URI. 0..1 S
placeTermId Plats-ID hos auktoritet. Utgår – använd placeTerm istället. 0..1 S
placeTermAuth Auktoritet för plats-ID. Används tillsammans med placeTermId. Utgår – använd placeTerm istället. 0..1 S
coordinates Koordinater enligt WGS84, RT90 eller SWEREF99. Sökparametern som motsvarar koordinaterna är en rektangel eller cirkel, dvs ett geografisk område (markerad på en karta i en tillämpning) inom vilken sökning sker. 0..1
geoDataExists Index för att söka fram objekt som har koordinater i coordinates, mha geoDataExists="j". Detta element skapas automatiskt av K-samsök centralt och ska inte levereras in. 0 S
boundingBox En geografisk rektangel (markerad på en karta) inom vilken sökning sker från en tillämpning. Mer info 0 S
pointDistance En geografisk cirkel (markerad på en karta) inom vilken sökning sker från en tillämpning. Mer info 0 S

Personer/Organisationer

Elementen för personer eller organisationer beskriver ett visst sammanhang för entiteten, t ex "Producerad". Det kan finnas flera sådana sammanhang definierade för en entitet. Följande element är person- eller organisationsrelaterade egenskaper för ett Context.

contextType Se contextType för Tider.
actor Fritextparameter som söker i alla fält för person- eller organisationsnamn. 0 S
contextLabel Specificerar det som står i contextType, kan vara en hänvisning till en rdf-resurs eller fritext. 0..1
firstName foaf:firstName Förnamn 0..1 S Fri
surname foaf:surname Efternamn 0..1 S Fri
fullName foaf:fullName Förnamn+blanksteg+Efternamn 0..1 S Fri
name foaf:name Allmänt ostrukturerat namn för fritextsökning 0..1 Fri
organization foaf:organization Organisationsnamn, om även personnamn anges innebär det att personen tillhör organisationen 0..1 S Fri
title foaf:title Titel, t ex "Disponent". Listan på titlar hittar du här: http://kulturarvsdata.se/resurser/Title 0..1 S
agent Auktoritet för en agent (person, organisation…), i form av URI. 0..n S
gender foaf:gender, fritext sträng. T.ex. kvinna anges som "K", man som "M". 0..1 S Fri
nameId Auktoriserat ID. Utgår – använd agent istället. 0..1 S
nameAuth Auktoritet för namn, t ex KB. Används tillsammans med nameId. Utgår – använd agent istället. 0..1 S

Relationer

isRelatedTo URI till relaterat objekt. Undvik denna default-relation om möjligt. Välj bland de fördefinierade relationstyperna. 0..n
containsInformationAbout Subjektet innehåller information om objektet 0..n
containsObject Subjektet innehåller objektet 0..n
isPartOf Är en del av, invers till containsObject 0..n
isFoundIn Är funnen i ett annat objekt, specialisering av isPartOf 0..n
hasBeenUsedIn Har brukats i 0..n
hasChild Överordnad 0..n
hasParent Underordnad 0..n
hasFind En fyndplats som har ett fynd 0..n
hasImage Bild som föreställer annat också eller är tagen från subjektet, t ex från en kyrka 0..n
hasObjectExample Urval av föremål som presenterar platsen på ett beskrivande sätt 0..n
hasPart Består av (essentiella delar av en helhet) 0..n
isDescribedBy Beskrivs av, t ex en litteraturreferens 0..n
visualizes För typen ”Objektavbildning”: URI till motivet 0..n
isVisualizedBy URI till en objektavbildning 0..n
owl:sameAs Använd denna standard om objektet har flera RDF-representationer 0..n
dcterms:replaces Använd denna standard om objektet ersätter ett tidigare objekt och därmed bytt URI 0..n

Övriga resurser

Nedanstående resurser pekas ut via egenskaper med samma namn. Här beskrivs vilka egenskaper de i sin tur definierar.

ItemNumber
ItemNumber är en publik (människoläsbar) identitet för ett objekt, t ex ett inventarienummer eller fornlämningsnummer och har följande element:

  • <type> – Typ av numering, t ex <type>inventarienummer</type>
  • <number>
ItemName
Objektets huvudsakliga benämning eller sakord. Specifik benämning av ett objekt, t ex itemName="Yxa". ItemName har följande element:

  • <type> – Typ av namn, t ex <sakord</type>
  • <name> – Etikett som beskriver objektet.
ItemSpecification
ItemSpecification har följande element:

  • <type> – Typ av specifikation, t ex produkttyp eller modell
  • <spec> – Modellbeteckning eller liknande
ItemMaterial
ItemMaterial har följande element:

  • <type> – Typ av material, t ex huvudmaterial eller tilläggsmaterial
  • <material> – Material, t ex <material>sten</material>
ItemDescription
ItemDescription har följande element:

  • <type> – Typ av beskrivning, t ex <type>föremålsbeskrivning</type>
  • <desc> – Beskrivning
ItemMeasurement
ItemMeasurement har följande element:

  • <type> – Typ av mått, t ex <type>längd</type>
  • <value> – Värde, t ex <value>23</value>
  • <unit> – Enhet, t ex <unit>mm</unit>
  • <qualifier> – Specifikation av vad som mäts, t ex egg eller i vilket läge det mäts, t ex förekonservering
ItemMark
Ska ungefär motsvara CIDOC-CRMs E 37 Mark. ItemMark har följande element:

  • <type> – Typ av tecken (text eller URI)
  • <form> – Tecknets form (text eller URI; kan vara flervärdigt)
ItemInscription
Ska ungefär motsvara CIDOC-CRMs E 34 Inscription. ItemInscription har följande element:

  • <type> – Typ av inskrift och/eller typ av återgivning (t.ex. transkribering, translitterering, normalisering, översättning)
  • <text> – Själva texten
Image
Observera att mediaMotiveWord indexeras i K-samsök Image har följande element:

  • <mediaType> – Mediatpy, t.ex. image/gif
  • <thumbnailSource> – Länk till källa för tummnagelbilden.
  • <lowresSource> – Länk till källa för lågupplöst bild.
  • <highresSource> – Länk till källaför högupplöst bild.
  • <byline> – Bildttext som ska innehålla fotograf och organisation.
  • <mediaMotiveWord> – Motivord
  • <copyright> – Organisation/Person som äger bilden.
  • <mediaLicense rdf:resource="http://kulturarvsdata.se/resurser/License#[spec]"/>
  • <mediaLicenseUrl rdf:resource="http://creativecommons.org/licenses/[spec]/2.5/se/">
Media
Observera att mediaMotiveWord indexeras i K-samsök Media har följande element:

  • <media>
  • <mediaLicense rdf:resource="http://kulturarvsdata.se/resurser/License#[spec]/">
  • <mediaLicenseUrl rdf:resource="http://creativecommons.org/licenses/[spec]/2.5/se/">
  • <byline>Bildttext som ska innehålla upphovsman och organisation</byline>
  • <copyright>Organisation/Person som äger media</copyright>
  • <link>direktlänk till media</link>
  • <mediaType>t ex application/pdf<Mediatyp”/>
  • </media>