acdh-oeaw/arche-schema

This is the repo for the ACDH-Ontology. The ontology is going to be used to describe resources in the acdh-repo.

ACDH-Ontology

This is the repo for the ACDH-Ontology. The ontology is going to be used to describe resources in the acdh-repo.

• For an interactive network visualization of the current ontology, please see here (thanks https://github.com/VisualDataWeb/WebVOWL)
• For a more static overview - please see here
• For a tabular view click here or here

Release cycle

Releasing new ontology versions requires lots of care. This is because the ontology determines behaviour of crucial ARCHE components (most notably the doorkeeper and the GUI) and because we must be able to assure already existing metadata are in line with the current ontology.

To assure new ontology release won't cause any trouble, the release process should go as follows:

• Create a new git branch (git checkout -b branchName, where branchName may be e.g. the next ontology version number).
• Make changes in the new branch, commit it and push to the GitHub (git push origin branchName).
• Create a pull request:
  • go to https://github.com/acdh-oeaw/arche-schema/compare
  • choose your branch in the compare: drop-down list
  • provide description of your changes
  • click the create pull request button
• Wait for approval from Martina, Mateusz and Norbert.
  The checklist:
  • ontology check script reports no errors
  • arche-lib-schema passes tests against the new ontology
  • arche-doorkeeper passes tests against the new ontology
  • dynamic root table displays new ontology corretly
  • we have scripts for updating old metadata so they are in line with the new ontology
• Merge pull request and create a new release.

Conventions

Version numbers

• major number change is constituted by ANY of:
  • adjusting or adding a cardinality restriction
  • removing a class, a property or an annotation property
  • removing an annotation property
• middle number change is constitude by ANY of:
  • adding a new class property or annotation property
  • adjusting class inheritance
  • adjusting property inheritance, range or domain
  • adjusting values of annotation properties driving the doorkeeper or GUI behaviour
• minor number change is constituted by:
  • a change with no impact on the doorkeeper and GUI (e.g. description or translation changes)

Classes

• As usual, class names have to start with a capital letter
• Use camelcase writing
• Uf a union of classes is required use a helper class
• Helper classes are all subclasses of acdh:Helper

Properties

• As usual, property names have to start with a lower case letter
• Use camelcase writing
• The direction of a property should be stated in the name of the property.
  • BAD acdh:title
  • GOOD acdh:hasTitle
  • BAD acdh:isMember
  • GOOD acdh:isMemberOf
• Remember about differences between datatype and object properties:
  • What is what and how it impacts the GUI?
    • A datatype property has a literal value (in layman's terms in a ttl it's value is written between ", e.g. _:someRes acdh:someProperty "literal value")
      • It can still be an URL/URI, just it will be stored as a string and will NOT create a separate repository resource (in GUI it will be displayed as a clickable link opening the URL in a new tab)
    • An object property has an URI value (in layman's terms in a ttl it's value is written between < and > or using a shorthand syntax, e.g. _:someRes acdh:someProperty <https://some/url> or _:someRes acdh:someProperty acdhi:otherResource)
      • Object property values create new repository resources
  • What can't be done (in owl)
    • A datatype property can't inherit from an object property (and vice versa)
    • A datatype property and an object property can't be equivalent
• A property meaning must not depend on a class context. If you feel a property meaning is (even a little) different for different classes, create two (or more) properties instead.
• Don't create both a property and its inverse version - it creates a lot of trouble and doesn't make providing data easier

Ranges

• Choose datatype property ranges wisely as they affect the doorkeeper and the GUI
  • Properties using xsd: types other than xsd:string and xsd:anyURI will be casted by a doorkeeper (e.g. if the range is xsd:date and ingested value is 2018 the doorkeeper will cast it to 2018-01-01)
  • Properties with range xsd:anyURI will be displayed in the GUI as clickable links opening in a new tab while all other datatype property values are displayed in the GUI just as they are

Restrictions

• Do not use qualified cardinality restrictions - the range is already defined by a property and shouldn't be redefined (or changed) in the restriction (in Protege terms it means setting as range rdfs:Literal for datatype properties and owl:Thing for object properties)
• Try to avoid duplicating same restrictions on all subclasses of a common parent - define the restriction on the parent instead (you won't loose anything as Protege still shows you such inheritet restrictions and it will allow to keep the ontology smaller and simpler)
• Model actual repository behaviour (take into account not all resources in the repository are of any of ACDH classes defined in this ontology but some rules stil apply to them, e.g. all must have a title and an identifier)
  • Use owl:Thing to denote any resource in the repository

Annotation properties

• Follow annotation property description closely

arche-schema's Issues

new properties `acdh:hasHeight` and `acdh:hasWidth`

why:

• mainly for images; would be used for IIIF-Manifest creation
• currently I (would) write this information in acdh:hasExtent, but from there it can't be processed further

domain: acdh:Resource
range: integer?
cardinality: 0-1

Create separate class for acdh:hasSubject range

Having a separate class for the acdh:hasSubject range will allow us to define separate doorkeeper check rules for the values.

acdh-oeaw/arche-doorkeeper#32
acdh-oeaw/arche-ref-sources#13

acdh:hasLiteralIdentifier has two ranges

The acdh:hasLiteralIdentifier has two ranges xsd:anyURI and xsd:string.

First, it causes trouble for the doorkeeper which does not know what range try to cast this property values to. And it choses wrongly, then e.g. the broken URLs checking script may try to check and report as broken non-URL identifiers.

Second (and more importantly), all URL identifiers should be provided using acdh:hasIdentifier so the acdh:hasLiteralIdentifier is only meant for values with range xsd:string.

Summing up the range of the acdh:hasLiteralIdentifier should be set to xsd:string

create human readable documentation

and host it via gh-pages
use https://github.com/RDFLib/pyLODE

Add acdh:automatedFill on acdh:hasHosting

(see also acdh-oeaw/arche-metadata-crawler#4)

Use property range to indicate that a lang tag is required

Currently we indicate that a property must have a lang tag by assigning it a dedicated annotation. A more RDFish would be to set its range to http://www.w3.org/1999/02/22-rdf-syntax-ns#langString instead.

allow `achd:hasUrl` for `acdh:Place`

currently all ARCHE-Classes (Person, Collection, Resource, ...) except Place are allowed to have the property acdh:hasUrl

IMHO this should be changed

Add image dimensions for existing data

Arche-schema v4.3.0 added achd:hasPixelWidth and acdh:hasPixelHeight and the arche-core 5.1.0 introduced extracting these metadata properties from the uploaded binaries. Still these properties need to be created for the data already stored in the repository.

hasIdentifier is a literal

shouldn't hasIdentifier be at least a URL? We actually even talked about limiting it to a specific set of baseurls.

acdh:hasLiteralIdentifier has two ranges

https://github.com/acdh-oeaw/arche-schema/blob/master/acdh-schema.owl#L1781-L1782

It should probably be only http://www.w3.org/2001/XMLSchema#anyURI

add DissService properties

https://vocabs.acdh.oeaw.ac.at/schema#hasDissService

The checkCardinalities.php script could be extended with checking datatype and lang

Questions regarding Ontology V2

I finally have some time en bloc to work on the finalisation of V2 of the ontology.

Some questions arise, which I do not want to post into the already very long discussion in the pull

1. acdh:hasAccessRestrcition: after some back and forth we came to the agreement, that it should only be used for binary content (i.e. entities of class Binary, Metadata or Image). Everything else, including Collection, is purely metadata and that is always public. For Collection we will have hasAccessRestrictionSummary which is going to be filled automatically depending on the children of the collection.
   Question: Are there any objections from the technical point of view to remove it from the class Collection?

2. Cardinalities (yet again). We had rather heated discussions about keeping or discarding cardinalities for properties that are automatically filled by the system or not. To summarise: Keep: OWL document which properties need to have a value in the end. Discard: It would make it more difficult for metadata creators and curators to distinguish which properties they must provide and which they don't
   A compromise was proposed: Keep the cardinalities for documenting somewhere which properties in the end need to have a value and in the root table also display which value is automatically filled.
   Question (directly to @zozlak): is that a way to go? Then I would reintroduce the cardinalities.

duplication of acdh:hasLongitude and acdh:hasLatitude with acdh:hasWKT

we should either drop acdh:hasLongitude and acdh:hasLatitude in favour of acdh:hasWKT or at least extend the doorkeeper to generate the acdh:hasWKT from acdh:hasLongitude and acdh:hasLatitude when the achd:hasWKT is missing bat lon/lat are provided.

change title of the schema

arche-schema/acdh-schema.owl

Line 21 in 4c73c17

<rdfs:label>ACDH Schema</rdfs:label>

now it is ACDH Schema maybe ARCHE Schema

hasNonLinkedIdentifier for all classes

currently hasNonLinkedIdentifier is restricted to p,c,r,m,pub which makes it impossible to save project specific IDs for entities like person, places or institutions although a lot of projects do carefully curate IDs for their entities. Information which for now can't be preserved properly on ARCHE-MD level

Develop a convention for marking properties which should not be used directly

Some properties like acdh:technical, acdh:hasLiteralIdentifier or acdh:disseminationService are only serving technical purposes and should not be used directly.

We need a convention to distinguish them so they are skipped by the arche-lib-schema and therefore not shown in the root table, not allowed by the doorkeeper, etc.

Rename acdh:hasService to acdh:hasDisseminationService

The ontology includes the technical property acdh:hasService to link a resource with a dissemination service. I think it would be better to rename it to acdh:hasDisseminationService. Although it is longer, it is more precise and does not leave too much room for speculation about what service is meant.

@zozlak what do you think?

Metadata cleanup for V2.0

Reference list of all issues

I am not firm in SQL. Thus here a list of actions for some of the items listed in #3 (comment)

• Property https://vocabs.acdh.oeaw.ac.at/schema#isPartOf with domain https://vocabs.acdh.oeaw.ac.at/schema#PlaceOrPublicationOrRepoObject is used in incompatible classes: https://vocabs.acdh.oeaw.ac.at/schema#DisseminationServiceParameter 6

  • -> exchange https://vocabs.acdh.oeaw.ac.at/schema#isPartOf with https://vocabs.acdh.oeaw.ac.at/schema#relation (If I understood you right you changed that anyway?)

• Property https://vocabs.acdh.oeaw.ac.at/schema#hasDepositor with domain https://vocabs.acdh.oeaw.ac.at/schema#RepoObject is used in incompatible classes: https://vocabs.acdh.oeaw.ac.at/schema#Project 1

  • -> remove https://vocabs.acdh.oeaw.ac.at/schema#hasDepositor from that project

• Resource 30304

  • too many values (2) for property https://vocabs.acdh.oeaw.ac.at/schema#hasFormat and lang
  • -> keep "audio/x-wav"

• Resource 35808

  • too many values (4) for property https://vocabs.acdh.oeaw.ac.at/schema#hasExtent and lang en
  • -> should be "100910000000 tokens, 40159000 documents, 305580000 paragraphs, 667000000 sentences"@en (merge all four values into one, separated by ', '
  • -> Same applies to acdh:hasExtent for Resources 3619, 36918, 36543 and 38513 (all contain "AMC Austrian Media Corpus" in acdh:hasTitle)

• Resource 36543

  • too many values (2) for property https://vocabs.acdh.oeaw.ac.at/schema#hasFormat and lang
  • -> keep "text/xml"

More will follow on Monday

acdh:hasLiteralIdentifier lacks acdh:ordering annotation property

hasContributor restrict domain

currently the domain for hasContributor is set to p,c,r,m,pub,pl,o,pe which imho makes not much sense for pe, pl, o, because what should acdhi:brunokreisy hasContributor acdhi:maxmayer exactly mean?

therefore I suggest to restrict the domain of hasContributor to p,c,r,m,pub

acdh:hasLatitude and acdh:hasLongitude have range xsd:float instead of xsd:decimal