Issue with the naming conventions for object properties to single occurances of a class

[DavidFichtmueller]

Suggestion

From the section about the naming convention:

The properties of a class start with a lowercase and use the lowerCamelCase naming convention. When a class contains a property which contains a list of another class we use the convention hasXXX where XXX is the class name. [...] When a class is directly nested (not through a list) we use the class name as property name.

The last sentence causes several issues. Not only does it break with common semantic web naming conventions (classes in upper case, properties in lower case), but more importantly, it causes two different terms (the class and the property pointing to a single instance of this class) to have the same URI and become thus undistinguishable to a computer. Also of the 7 object properties with a single instance of a class for the Digital Specimen FDO, only 4 follow this convention.

• Assertion
  • ods:AssertionByAgent
• DigitalSpecimen
  • ods:TombstoneMetadata
• EntityRelationship
  • ods:RelationshipAccordingToAgent
• Event
  • ods:Location
• Location
  • ods:GeoReference
  • ods:GeologicalContext
• TombstoneMetadata
  • ods:TombstonedByAgent

Our recommendation would be to change the naming convention to the following rules:

• all object properties start with a "has" followed by the class name it is pointing to. If there are multiple instances of the class allowed, then the class name is written in the plural form (usually, by adding an s)¹

Allow for meaningful exceptions to this rule, to clarify some use cases, e.g. the alternative solution mentioned from #168 would then be ods:hasRelatedIdentifers.

The terms effected by this change would be:

class	old name	new name
Agent
	ods:hasIdentifier	ods:hasIdentifiers
Assertion
	ods:AssertionByAgent	ods:hasAgent2
DigitalSpecimen
	ods:hasMaterialEntity	ods:hasMaterialEntitys
	ods:hasIdentification	ods:hasIdentifications
	ods:hasAssertion	ods:hasAssertions
	ods:hasEvent	ods:hasEvents
	ods:hasEntityRelationship	ods:hasEntityRelationships
	ods:hasCitation	ods:hasCitations
	ods:hasIdentifier	ods:hasIdentifiers
	ods:hasChronometricAge	ods:hasChronometricAges
	ods:hasAgent	ods:hasAgents
	ods:TombstoneMetadata	ods:hasTombstoneMetadata
EntityRelationship
	ods:RelationshipAccordingToAgent	ods:hasAgent2
Event
	ods:hasAssertion	ods:hasAssertions
	ods:Location	ods:hasLocation
Identification
	ods:hasCitation	ods:hasCitations
	ods:hasTaxonIdentification	ods:hasTaxonIdentifications 3
Location
	ods:GeoReference	ods:hasGeoReference
	ods:GeologicalContext	ods:hasGeologicalContext
MaterialEntity
	ods:hasIdentification	ods:hasIdentifications
	ods:hasAssertion	ods:hasAssertions
	ods:hasEntityRelationship	ods:hasEntityRelationships
	ods:hasCitation	ods:hasCitations
	ods:hasIdentifier	ods:hasIdentifiers
	ods:hasEvent	ods:hasEvents
	ods:hasAgent	ods:hasAgents
TombstoneMetadata
	ods:TombstonedByAgent	ods:hasAgent2

Footnotes

1. Lets hope we never need a sheep or deer class. ↩

2. these properties could also get more descriptive names as described in the meaningful exception clause ↩ ↩² ↩³

3. with the plural as it is currently defined, also see ods:hasTaxonIdentification: should not allow for multiple TaxonIdentification #170 ↩

[samleeflang]

Hi David, thanks for pointing out this issue. We have been struggling with this particular case for a bit. In general, we tried to align with TDWG and in particular LTC. This means the structure ods:hasXxx (without the s) for arrays of objects. See for example: ltc:hasTaxon. If we put an s behind our terms, that would break convention on that part. However, looking at several other naming conventions, this is a structure generally used. I will make the appropriate changes. To summarize, this would make four cases:

• ods:xxx -> for strings/numbers
• ods:isXXX -> for booleans
• ods:hasXXX -> for single nested object
• ods:hasXXXs -> for array of nested objects

However, I propose that we would then add a fifth case:

• ods:xxxs -> an array of strings/numbers
  I would have to do a full check, at the moment I know there is one term which will change ods:language -> ods:languages

Feel free to provide additional comments, in the meantime I will start implementing these changes.

Regards,
Sam

[DavidFichtmueller]

This is a useful change to add the s for language, since it is an array. However you might not want to add this particular rule to the naming convention chapter in the introduction, because of the two ods elements citationRemarks and assertionRemarks. Both being single strings and aligned to the different Remarks elements from DwC. And while it is perfectly reasonable to have exceptions to the rules from the convention, here we would have more exceptions than instances, where the rule is followed, so it would be better not to mention this rule explicitly.
I still agree with changing ods:language to ods:languages, though.