Machine Annotation Service Quick Reference Guide

On this page

Overview

Requirements

The tables below provides a summary of the required classes and terms. Term requirements are subject to the use of the parent class where a term that belongs to an optional class are required if and only if, their parent class is in use.

Required Classes
Class Label Required
ods:MachineAnnotationService Machine Annotation Service True
Required Terms
Term Label Class Required
schema:value Value ods:EnvironmentalVariable True
dcterms:title Title ods:Identifier True
ods:batchingPermitted Batching Permitted ods:MachineAnnotationService True
ods:timeToLive Time To Live ods:MachineAnnotationService True
ods:containerTag Container Tag ods:MachineAnnotationService True
ods:containerImage Container Image ods:MachineAnnotationService True
schema:creator Creator ods:MachineAnnotationService True
schema:dateCreated Date Created ods:MachineAnnotationService True
schema:name Name ods:MachineAnnotationService True
ods:fdoType Fdo Type ods:MachineAnnotationService True
schema:identifier Identifier ods:MachineAnnotationService True
schema:dateModified Date Modified ods:MachineAnnotationService True
dcterms:identifier Identifier ods:RelatedPID True
ods:secretKeyRef Secret Key Ref ods:SecretVariable True
ods:hasAgents Has Agents ods:TombstoneMetadata True
ods:tombstoneText Tombstone Text ods:TombstoneMetadata True
ods:tombstoneDate Tombstone Date ods:TombstoneMetadata True

Open Digital Specimen

ods:Agent

Agent schema:identifier schema:name ods:hasRoles schema:email schema:url ods:hasIdentifiers
ods:Agent Class
Qualified Term Agent
Label Agent
Definition A generic agent class, containing information about the actor who performed an activity. This could be a person, an organization or a machine.
schema:identifier Property
Qualified Term schema:identifier
Label Identifier
Definition The primary unique identifier of the Agent object. All identifiers will also be added to the ods:hasIdentifiers array
Examples
  • http://www.wikidata.org/entity/Q66581882
  • https://orcid.org/0000-0002-1825-0097
  • https://hdl.handle.net/20.5000.1025/XXX-XXX-XXX
schema:name Property
Qualified Term schema:name
Label Name
Definition Full name of the agent
Examples
  • John Smith
  • Sam Leeflang
ods:hasRoles Property
Qualified Term ods:hasRoles
Label Has Roles
Definition Contains all roles associated with the agent in the context of the Digital Object. Should always contain at least one role
schema:email Property
Qualified Term schema:email
Label Email
Definition Email of the agent
Examples
  • dissco@dissco.eu
schema:url Property
Qualified Term schema:url
Label URL
Definition URL to a website of the agent
Examples
  • https://dissco.eu
ods:hasIdentifiers Property
Qualified Term ods:hasIdentifiers
Label Has Identifiers
Definition Contains all identifiers associated with the agent

ods:EnvironmentalVariable

EnvironmentalVariable schema:name schema:value
ods:EnvironmentalVariable Class
Qualified Term EnvironmentalVariable
Label Environmental Variable
Definition A class containing information about which (non-secret) environmental values the application requires.
schema:name Property
Qualified Term schema:name
Label Name
Definition The name of a non-sensitive property or environmental variable
Examples
  • server.port
  • spring.profiles.active
schema:value Property
Qualified Term schema:value
Label Value
Definition Value to be stored in the name field. NOT for sensitive information.
Examples
  • 8080
  • web-profile

ods:Identifier

Identifier dcterms:title dcterms:type dcterms:identifier dcterms:format dcterms:subject ods:isPartOfLabel ods:gupriLevel ods:identifierStatus
ods:Identifier Class
Qualified Term Identifier
Label Identifier
Definition A generic Identifier class which can be attached to multiple classes. It captures information about any identifier of the class.
dcterms:title Property
Qualified Term dcterms:title
Label Title
Definition A name for the identifier
Examples
  • abcd:UnitID
  • dwc:occurrenceID
  • ORCID
  • wikidata
  • ROR
  • cetaf stable identifier
dcterms:type Property
Qualified Term dcterms:type
Label Type
Definition The type of the value in the `dcterms:identifier` field
Examples
  • DOI
dcterms:identifier Property
Qualified Term dcterms:identifier
Label Identifier
Definition The value for the identifier
Examples
  • BMNH(E)1902475
  • RGM.800315
  • https://orcid.org/0000-0002-5669-2769
  • https://www.wikidata.org/wiki/Q66581882
  • https://ror.org/00bv4cx53
dcterms:format Property
Qualified Term dcterms:format
Label Format
Definition All possible mime types of content that can be returned by identifier in case the identifier is resolvable. Plain UUIDs for example do not have a dc:format return type, as they are not resolvable on their own. For a list of MIME types see the list maintained by IANA: http://www.iana.org/assignments/media-types/index.html, in particular the text http://www.iana.org/assignments/media-types/text/ and application http://www.iana.org/assignments/media-types/application/ types. Frequently used values are text/html, text/xml, application/rdf+xml, application/json
Examples
  • ['application/json', 'text/html']
  • ['application/rdf+xml', 'application/ld+json']
dcterms:subject Property
Qualified Term dcterms:subject
Label Subject
Definition Additional keywords that the publisher may prefer to be attached to the identifier
Examples
  • ['erecolnat', 'As available on label']
  • ['Registratie nummer', 'RMNH identifier']
ods:isPartOfLabel Property
Qualified Term ods:isPartOfLabel
Label Is Part Of Label
Definition Indicates whether the identifier is part of the physical label
ods:gupriLevel Property
Qualified Term ods:gupriLevel
Label GUPRI Level
Definition Indicates whether the identifier is a persistent identifier
ods:identifierStatus Property
Qualified Term ods:identifierStatus
Label Identifier Status
Definition Indicates the status of the identifier

ods:MachineAnnotationService

MachineAnnotationService schema:identifier ods:fdoType ods:status schema:version schema:name schema:description schema:dateCreated schema:dateModified schema:creator ods:containerImage ods:containerTag ods:hasTargetDigitalObjectFilter schema:creativeWorkStatus schema:codeRepository schema:programmingLanguage ods:serviceAvailability schema:maintainer schema:license schema:ContactPoint ods:slaDocumentation ods:topicName ods:maxReplicas ods:batchingPermitted ods:timeToLive ods:hasTombstoneMetadata ods:hasEnvironmentalVariables ods:hasSecretVariables
ods:MachineAnnotationService Class
Qualified Term MachineAnnotationService
Label Machine Annotation Service
Definition A machine agent which will perform an action on the Digital Object potentially resulting in a new annotation on the object
schema:identifier Property
Qualified Term schema:identifier
Label Identifier
Definition Handle of the Machine Annotation Service
Examples
  • https://hdl.handle.net/20.5000.1025/XXX-XXX-XXX
  • https://hdl.handle.net/20.5000.1025/JH1-C37-E7F
ods:fdoType Property
Qualified Term ods:fdoType
Label Fdo Type
Definition The DOI to the FDO type of the object
Examples
  • https://doi.org/21.T11148/417a4f472f60f7974c12
ods:status Property
Qualified Term ods:status
Label Status
Definition The status of the Digital Object. A digital object can be in Draft, when it is not published yet. Active when it is published and the object is active and Tombstone which means the object has been archived.
schema:version Property
Qualified Term schema:version
Label Version
Definition The version of the object, each change generates a new version. The version starts at 1 and each change will increment the version number with 1
schema:name Property
Qualified Term schema:name
Label Name
Definition Name of the Machine Annotation Service as provided by the user, https://schema.org/name
Examples
  • GBIF Linker Service
schema:description Property
Qualified Term schema:description
Label Description
Definition Description of the Machine Annotation Service as provided by the user, https://schema.org/description
Examples
  • A service that links GBIF records to a DiSSCo Digital Specimen. It creates an EntityRelationship indicating the relationship
schema:dateCreated Property
Qualified Term schema:dateCreated
Label Date Created
Definition Timestamp of creation. Internally generated, following the ISO Date Time Format yyyy-MM-dd'T'HH:mm:ss.SSSXXX
Examples
  • 2021-06-01T12:00:000Z
schema:dateModified Property
Qualified Term schema:dateModified
Label Date Modified
Definition Timestamp of last modification. Internally generated, following the ISO Date Time Format yyyy-MM-dd'T'HH:mm:ss.SSSXXX
Examples
  • 2021-06-06T13:22:00.445Z
schema:creator Property
Qualified Term schema:creator
Label Creator
Definition Contains information about the creator of this MachineAnnotationService Digital Object, the agent creating this record in DiSSCo's system
ods:containerImage Property
Qualified Term ods:containerImage
Label Container Image
Definition The URI to the location of the image in a public container repository. Should only contain the image name and not the tag
Examples
  • public.ecr.aws/dissco/mindat-georeferencing
ods:containerTag Property
Qualified Term ods:containerTag
Label Container Tag
Definition The image tag of the container image. This should not be `latest` but point to a specific version. On an update of the application a new image tag should be generated and the Digital Object should be updated
Examples
  • sha-cb76994
ods:hasTargetDigitalObjectFilter Property
Qualified Term ods:hasTargetDigitalObjectFilter
Label Has Target Digital Object Filter
Definition Filters describing the criteria that a Digital Object must meet in order to apply the MAS. No filters implies the MAS may run on *any* digital object. Field names are given in JSON paths, and accepted values for that field are provided as an arrays. An `*` can be used as a wildcard, indicating any value is seen as valid
Examples
  • {$['ods:type']: ['https://doi.org/21.T11148/894b1e6cad57e921764e'], $['ods:topicDiscipline']: ['Astrogeology', 'Geology', 'Palaeontology', 'Other Geodiversity', 'Unclassified'], $['ods:hasEvent'][*]['ods:Location']['dwc:locality']: ['*']}
schema:creativeWorkStatus Property
Qualified Term schema:creativeWorkStatus
Label Creative Work Status
Definition The current status of the service in terms of its service lifecycle
Examples
  • Alpha
  • Production
schema:codeRepository Property
Qualified Term schema:codeRepository
Label Code Repository
Definition Link to the repository where the un-compiled, human readable code and related code is located (SVN, GitHub, CodePlex)
Examples
  • https://github.com/rtdeb/GeoPick
  • https://github.com/DiSSCo/dissco-core-backend
schema:programmingLanguage Property
Qualified Term schema:programmingLanguage
Label Programming Language
Definition The primary programming language used by the MAS
Examples
  • Python
  • Java 17
ods:serviceAvailability Property
Qualified Term ods:serviceAvailability
Label Service Availability
Definition Availability commitment in uptime percentage of the service provider as described in the SLA
Examples
  • 99.9%
  • 95.0%
schema:maintainer Property
Qualified Term schema:maintainer
Label Maintainer
Definition Party maintaining the code, could be an schema:Organisation or a schema:Person
schema:license Property
Qualified Term schema:license
Label License
Definition A license document which applies to this Machine Annotation Service
Examples
  • https://opensource.org/license/Apache-2.0
  • https://opensource.org/license/mit
schema:ContactPoint Class
Qualified Term schema:ContactPoint
Label Contact Point
Definition The contact point for support and information for the Machine Annotation Service
ods:slaDocumentation Property
Qualified Term ods:slaDocumentation
Label Sla Documentation
Definition Link to SLA documentation of the Machine Annotation Service
Examples
  • https://www.dissco.tech/sla/mas
ods:topicName Property
Qualified Term ods:topicName
Label Topic Name
Definition Kafka topic through which the MAS receives messages. Defaults to PID of the Machine Annotation Service
Examples
  • p3r-7ff-s4n
  • fsj-g4m-l47
ods:maxReplicas Property
Qualified Term ods:maxReplicas
Label Max Replicas
Definition The maximum amount of this MAS that can simultaneously run without causing issues
Examples
  • 3
ods:batchingPermitted Property
Qualified Term ods:batchingPermitted
Label Batching Permitted
Definition Whether or not this Machine Annotation Service can create Batch Annotations. Machine Annotations Service outputs must then comply with batchMetadata, see https://schemas.dissco.tech/schemas/annotations/0.1.0/annotation-event.json
ods:timeToLive Property
Qualified Term ods:timeToLive
Label Time To Live
Definition Time in milliseconds the MAS message may remain in the Kafka Queue before being marked as timed out. Min 1 hour.
Examples
  • 86400000
  • 43200000
ods:hasTombstoneMetadata Property
Qualified Term ods:hasTombstoneMetadata
Label Has Tombstone Metadata
Definition Object containing the tombstone metadata of the object
ods:hasEnvironmentalVariables Property
Qualified Term ods:hasEnvironmentalVariables
Label Has Environmental Variables
Definition Environmental variables to supply to the Machine Annotation Service, non-sensitive
ods:hasSecretVariables Property
Qualified Term ods:hasSecretVariables
Label Has Secret Variables
Definition Secret variables to supply to the Machine Annotation Service, sensitive

ods:RelatedPID

RelatedPID dcterms:identifier schema:identifier ods:relationshipType
ods:RelatedPID Class
Qualified Term RelatedPID
Label Related PID
Definition Indicates to which other Digital Object the tombstoned record is related to. This can be used when a digital object has been split or merged into other Digital Objects.
dcterms:identifier Property
Qualified Term dcterms:identifier
Label Identifier
Definition The PID of the related object, used in cases of `ods:Annotation`, `ods:DigitalMedia` and `ods:DigitalSpecimen`
Examples
  • https://doi.org/10.22/XXX-XXX-XXX
schema:identifier Property
Qualified Term schema:identifier
Label Identifier
Definition The PID of the related object, used in cases of `ods:DataMapping`, `ods:SourceSystem` and `ods:MachineAnnotationService`
Examples
  • https://hdl.handle.net/20.5000.1025/XXX-XXX-XXX
ods:relationshipType Property
Qualified Term ods:relationshipType
Label Relationship Type
Definition The type of relationship between the tombstoned object and the related object
Examples
  • RelatedTo
  • IsDuplicateOf
  • IsReplacedWith

ods:Role

Role schema:roleName schema:startDate schema:endDate schema:position
ods:Role Class
Qualified Term Role
Label Role
Definition A role is a named entity that can be assigned to an agent. It is used to describe the function of an agent in a specific context.
schema:roleName Property
Qualified Term schema:roleName
Label Role Name
Definition The category that best matches the nature of a role of an Agent
Examples
  • collector
  • preparer
  • identifier
  • recorder
schema:startDate Property
Qualified Term schema:startDate
Label Start Date
Definition Date the agent began the role
Examples
  • 2023-10-02T12:31:34.806Z
schema:endDate Property
Qualified Term schema:endDate
Label End Date
Definition Date the agent ended the role
Examples
  • 2023-09-02T12:31:34.806Z
schema:position Property
Qualified Term schema:position
Label Position
Definition Can be used to indicate the order of importance when there are multiple agents with the same role. Lower order means higher importance.
Examples
  • 1
  • 2
  • 3

ods:SecretVariable

SecretVariable schema:name ods:secretKeyRef
ods:SecretVariable Class
Qualified Term SecretVariable
Label Secret Variable
Definition A class containing information about which secret the Machine Annotation Service requires. The secret value will be supplied separately to DiSSCo.
schema:name Property
Qualified Term schema:name
Label Name
Definition The name of an environmental variable stored remotely
Examples
  • database.password
  • keycloak.secret
ods:secretKeyRef Property
Qualified Term ods:secretKeyRef
Label Secret Key Ref
Definition The name of the key stored in the secret store. NOT the secret's value.
Examples
  • db-password

ods:TombstoneMetadata

TombstoneMetadata ods:tombstoneDate ods:tombstoneText ods:hasAgents ods:hasRelatedPIDs
ods:TombstoneMetadata Class
Qualified Term TombstoneMetadata
Label Tombstone Metadata
Definition The tombstone metadata about the tombstoned digital object, including the what, who and when of the tombstoning.
ods:tombstoneDate Property
Qualified Term ods:tombstoneDate
Label Tombstone Date
Definition Timestamp the Digital Object was tombstoned and no longer active. Following the ISO Date Time Format yyyy-MM-dd'T'HH:mm:ss.SSSXXX
Examples
  • 2021-06-01T12:00:000Z
ods:tombstoneText Property
Qualified Term ods:tombstoneText
Label Tombstone Text
Definition A reason why the Digital Object was tombstoned
Examples
  • This is a duplicate of XXX
  • This object was made by mistake
ods:hasAgents Property
Qualified Term ods:hasAgents
Label Has Agents
Definition The agent(s) who tombstoned the Digital Object, contains an ods:Agent object
ods:hasRelatedPIDs Property
Qualified Term ods:hasRelatedPIDs
Label Has Related Pi Ds
Definition The PIDs of the object the tombstoned object is related to

ods:schema:ContactPoint

schema:description schema:email schema:url schema:telephone
schema:description Property
Qualified Term schema:description
Label Description
Definition General description of the contact point
schema:email Property
Qualified Term schema:email
Label Email
Definition Email of the contact point
schema:url Property
Qualified Term schema:url
Label URL
Definition URL of the contact point, this could be a link to a contact form or a link to a github issues page
schema:telephone Property
Qualified Term schema:telephone
Label Telephone
Definition Telephone number of the contact point