001/* 002 * Copyright 2021 Global Biodiversity Information Facility (GBIF) 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016package org.gbif.dwc.terms; 017 018import java.io.Serializable; 019import java.net.URI; 020import java.util.ArrayList; 021import java.util.List; 022 023public enum GbifTerm implements Term, AlternativeNames, Serializable { 024 // row types 025 026 /** 027 * The <a href="http://rs.gbif.org/terms/1.0/Description">GBIF Taxon Description</a> 028 * extension row type. 029 */ 030 Description(GbifTerm.GROUP_ROW_TYPE), 031 032 /** 033 * The <a href="http://rs.gbif.org/terms/1.0/Distribution">GBIF Species Distribution</a> 034 * extension row type. 035 */ 036 Distribution(GbifTerm.GROUP_ROW_TYPE), 037 038 /** 039 * The <a href="http://rs.gbif.org/terms/1.0/Identifier">GBIF Alternative Identifiers</a> 040 * extension row type. 041 */ 042 Identifier(GbifTerm.GROUP_ROW_TYPE), 043 044 /** 045 * The deprecated <a href="http://rs.gbif.org/terms/1.0/Image">GBIF Simple Images</a> 046 * extension row type. 047 */ 048 Image(GbifTerm.GROUP_ROW_TYPE, "Images"), 049 050 /** 051 * The <a href="http://rs.gbif.org/terms/1.0/References">GBIF Literature References</a> 052 * extension row type. 053 */ 054 Reference(GbifTerm.GROUP_ROW_TYPE, "References"), 055 056 /** 057 * The <a href="http://rs.gbif.org/terms/1.0/SpeciesProfile">GBIF Species Profile</a> 058 * extension row type. 059 */ 060 SpeciesProfile(GbifTerm.GROUP_ROW_TYPE, "SpeciesMiniProfile", "SpeciesInfo", "SpeciesData", "SpeciesFactsheet"), 061 062 /** 063 * The <a href="http://rs.gbif.org/terms/1.0/TypesAndSpecimen">GBIF Types and Specimen</a> 064 * extension row type. 065 */ 066 TypesAndSpecimen(GbifTerm.GROUP_ROW_TYPE, "Specimen", "Types", "TypeDesignation"), 067 068 /** 069 * The <a href="http://rs.gbif.org/terms/1.0/VernacularNames">GBIF Vernacular Names</a> 070 * extension row type. 071 */ 072 VernacularName(GbifTerm.GROUP_ROW_TYPE, "VernacularNames", "Vernacular", "Vernaculars"), 073 074 /** 075 * The <a href="http://rs.gbif.org/terms/1.0/Multimedia">GBIF Simple Multimedia</a> 076 * extension row type. 077 */ 078 Multimedia(GbifTerm.GROUP_ROW_TYPE), 079 080 /** 081 * The <a href="http://rs.gbif.org/terms/1.0/DNADerivedData">DNA Derived Data</a> 082 * extension row type. 083 */ 084 DNADerivedData(GbifTerm.GROUP_ROW_TYPE), 085 086 /** 087 * The UUID key for the dataset registered in GBIF. 088 */ 089 datasetKey(GbifTerm.GROUP_DATASET), 090 091 /** 092 * The ISO 3166 2-letter code of the country of the organization that publishes the dataset to which the occurrence belongs. 093 */ 094 publishingCountry(GbifTerm.GROUP_DATASET), 095 096 /** 097 * Numerical, stable identifier assigned by GBIF to an Occurrence record. 098 */ 099 gbifID(DwcTerm.GROUP_OCCURRENCE), 100 101 /** 102 * Timestamp of the last time the record was (re)interpreted by GBIF. 103 */ 104 lastInterpreted(DwcTerm.GROUP_OCCURRENCE), 105 106 /** 107 * The uncertainty radius for the latitude and longitude in decimal degrees. 108 */ 109 @Deprecated 110 coordinateAccuracy(DwcTerm.GROUP_OCCURRENCE), 111 112 /** 113 * Elevation in metres above sea level (altitude). 114 * <p> 115 * The elevation is the absolute vertical position of the observed location (z-coordinate). 116 * If depth is given or not will not impact the 3-dimensional position. 117 * For example a location 100m below the surface of a lake in 2000m altitude has a depth of 100 and 118 * an elevation of 1900. 119 * </p> 120 * <p> 121 * If minimum and maximum values are given the elevation is calculated using the equation: 122 * <code>(minimumElevationInMeters + maximumElevationInMeters) / 2</code>. 123 * For consistency and ease of use GBIF decided to always use a value in metres plus its accuracy instead of 124 * min/max values which are sometimes used in Darwin Core. See also depth & distanceAboveSurface. 125 * </p> 126 */ 127 elevation(DwcTerm.GROUP_LOCATION), 128 129 /** 130 * Elevation accuracy is the uncertainty for the elevation in metres. 131 * <p> 132 * The elevation accuracy is calculated using the equation: <code>(maximumElevationInMeters - minimumElevationInMeters) / 2</code> 133 * in case a minimum and maximum verbatim value is given. 134 * </p> 135 */ 136 elevationAccuracy(DwcTerm.GROUP_LOCATION), 137 138 /** 139 * Depth in metres below the surface. 140 * <p> 141 * Complimentary and relative to elevation, depth indicates the distance to the earth surface, whether that is water 142 * or ground. 143 * For example a location 100m below the surface of a lake in 2000m altitude has a depth of 100 and 144 * an elevation of 1900. 145 * </p> 146 * <p> 147 * The depth is calculated using the equation: <code>(minimumDepthInMeters + maximumDepthInMeters) / 2</code>. 148 * For consistency and ease of use GBIF decided to always use a value in meters plus it's accuracy instead of 149 * min/max values which are sometimes used in Darwin Core. See also elevation & distanceAboveSurface. 150 * </p> 151 */ 152 depth(DwcTerm.GROUP_LOCATION), 153 154 /** 155 * Depth accuracy is the uncertainty for the depth in metres. 156 * <p> 157 * The depth accuracy is calculated using the equation: <code>(maximumDepthInMeters - minimumDepthInMeters) / 2</code> 158 * in case a minimum and maximum verbatim value is given. 159 * </p> 160 */ 161 depthAccuracy(DwcTerm.GROUP_LOCATION), 162 163 /** 164 * Replaced by Darwin Core terms <a href="http://rs.tdwg.org/dwc/terms/minimumDistanceAboveSurfaceInMeters">dwc:minimumDistanceAboveSurfaceInMeters</a> 165 * and <a href="http://rs.tdwg.org/dwc/terms/maximumDistanceAboveSurfaceInMeters">dwc:maximumDistanceAboveSurfaceInMeters</a>. 166 */ 167 @Deprecated 168 distanceAboveSurface(DwcTerm.GROUP_LOCATION), 169 170 /** 171 * Replaced by Darwin Core terms <a href="http://rs.tdwg.org/dwc/terms/minimumDistanceAboveSurfaceInMeters">dwc:minimumDistanceAboveSurfaceInMeters</a> 172 * and <a href="http://rs.tdwg.org/dwc/terms/maximumDistanceAboveSurfaceInMeters">dwc:maximumDistanceAboveSurfaceInMeters</a>. 173 */ 174 @Deprecated 175 distanceAboveSurfaceAccuracy(DwcTerm.GROUP_LOCATION), 176 177 /** 178 * The distance in metres from a known centroid, e.g. a country centroid. 179 */ 180 distanceFromCentroidInMeters(DwcTerm.GROUP_LOCATION), 181 182 /** 183 * Any issue found during processing and interpretation or the record. 184 * See <a href="https://gbif.github.io/gbif-api/apidocs/org/gbif/api/vocabulary/OccurrenceIssue.html">OccurrenceIssue enumeration</a> for possible values. 185 */ 186 issue(DwcTerm.GROUP_OCCURRENCE), 187 188 /** 189 * Issue found during processing and interpretation or the record related to a specific checklist. 190 * See <a href="https://gbif.github.io/gbif-api/apidocs/org/gbif/api/vocabulary/OccurrenceIssue.html">OccurrenceIssue enumeration</a> for possible values. 191 */ 192 taxonomicIssue(DwcTerm.GROUP_OCCURRENCE), 193 194 /** 195 * Issue found during processing and interpretation or the record that are non-taxonomic. 196 */ 197 nonTaxonomicIssue(DwcTerm.GROUP_OCCURRENCE), 198 199 /** 200 * The environments the interpreted taxon is known to live in according to the checklist used, 201 * e.g. MARINE, BRACKISH, FRESHWATER or TERRESTRIAL. A property of the taxon, not of the occurrence. 202 */ 203 environments(DwcTerm.GROUP_TAXON), 204 205 /** 206 * The media type given as Dublin Core type values, in particular StillImage, MovingImage or Sound. 207 */ 208 mediaType(DwcTerm.GROUP_OCCURRENCE), 209 210 // experimental Occurrence properties 211 infraspecificMarker(DwcTerm.GROUP_OCCURRENCE), 212 213 // Types and Specimen checklist extension 214 typeDesignatedBy(DwcTerm.GROUP_OCCURRENCE), 215 typeDesignationType(DwcTerm.GROUP_OCCURRENCE), 216 217 /** 218 * Boolean indicating that a valid latitude and longitude exists. 219 * Even if existing it might still have issues, see hasGeospatialIssues and issue. 220 */ 221 hasCoordinate(DwcTerm.GROUP_OCCURRENCE), 222 223 /** 224 * Boolean indicating that some spatial validation rule has not passed. 225 * Primarily used to indicate that the record should not be displayed on a map. 226 */ 227 hasGeospatialIssues(DwcTerm.GROUP_OCCURRENCE), 228 229 230 /** 231 * The checklist key. 232 * <p> 233 * The taxonomic checklist to use when search using a taxonKey, a higher taxonKey e.g. phylumKey 234 * or when searching with a scientific name 235 * </p> 236 */ 237 checklistKey(DwcTerm.GROUP_TAXON), 238 239 /** 240 * The GBIF backbone key. 241 * <p> 242 * The best matching, accepted GBIF backbone name usage representing this occurrence. 243 * In case the verbatim scientific name and its classification can only be matched to a higher rank this will 244 * represent the lowest matching rank. In the worst case this could just be for example Animalia. 245 * </p> 246 * <p> 247 * In contrast dwc:taxonID is only used for the source ids similar to occurrenceID 248 * </p> 249 */ 250 taxonKey(DwcTerm.GROUP_TAXON), 251 252 253 /** 254 * The GBIF backbone key of the accepted taxon key. 255 */ 256 acceptedTaxonKey(DwcTerm.GROUP_TAXON), 257 258 /** 259 * The key to the accepted kingdom in the taxonomy. 260 */ 261 kingdomKey(DwcTerm.GROUP_TAXON), 262 263 /** 264 * The key to the accepted phylum in the taxonomy. 265 */ 266 phylumKey(DwcTerm.GROUP_TAXON), 267 268 /** 269 * The key to the accepted class in the taxonomy. 270 */ 271 classKey(DwcTerm.GROUP_TAXON), 272 273 /** 274 * The key to the accepted order in the taxonomy. 275 */ 276 orderKey(DwcTerm.GROUP_TAXON), 277 278 /** 279 * The key to the accepted superfamily in the taxonomy. 280 */ 281 superfamilyKey(DwcTerm.GROUP_TAXON), 282 283 /** 284 * The key to the accepted family in the taxonomy. 285 */ 286 familyKey(DwcTerm.GROUP_TAXON), 287 288 /** 289 * The key to the accepted subfamily in the taxonomy. 290 */ 291 subfamilyKey(DwcTerm.GROUP_TAXON), 292 293 /** 294 * The key to the accepted tribe in the taxonomy. 295 */ 296 tribeKey(DwcTerm.GROUP_TAXON), 297 298 /** 299 * The key to the accepted subtribe in the taxonomy. 300 */ 301 subtribeKey(DwcTerm.GROUP_TAXON), 302 303 /** 304 * The key to the accepted genus in the taxonomy. 305 */ 306 genusKey(DwcTerm.GROUP_TAXON), 307 308 /** 309 * The key to the accepted subgenus in the taxonomy. 310 */ 311 subgenusKey(DwcTerm.GROUP_TAXON), 312 313 /** 314 * The backbone key to the accepted species. 315 * In case the taxonKey is of a higher rank than species (e.g. genus) speciesKey is null. 316 * In case taxonKey represents an infraspecific taxon the speciesKey points to the species 317 * the infraspecies is classified as. In case of taxonKey being a species the speciesKey is the same. 318 */ 319 speciesKey(DwcTerm.GROUP_TAXON), 320 321 /** 322 * The canonical name without authorship of the accepted species. 323 */ 324 species(DwcTerm.GROUP_TAXON), 325 326 // experimental Taxon properties 327 canonicalName(DwcTerm.GROUP_TAXON), 328 nameType(DwcTerm.GROUP_TAXON), 329 330 /** 331 * The scientific name the type associated acceptedNubKey. 332 */ 333 acceptedScientificName(DwcTerm.GROUP_TAXON), 334 335 /** 336 * Scientific name as provided by the source. 337 */ 338 verbatimScientificName(DwcTerm.GROUP_TAXON), 339 340 /** 341 * The scientific name the type status of this specimen applies to. 342 * Term proposed in Darwin Core, but not yet ratified. 343 */ 344 typifiedName(DwcTerm.GROUP_IDENTIFICATION), 345 346 /** 347 * The kind of protocol used when the record was last crawled by GBIF. 348 * See <a href="http://gbif.github.io/gbif-api/apidocs/org/gbif/api/vocabulary/EndpointType.html">EndpointType enumeration</a> for possible values. 349 */ 350 protocol(GbifTerm.GROUP_CRAWLING), 351 352 /** 353 * The date this record was last parsed from raw xml/json into a verbatim GBIF record. 354 */ 355 lastParsed(GbifTerm.GROUP_CRAWLING), 356 357 /** 358 * The date this record was last crawled/harvested by GBIF from the endpoint. 359 */ 360 lastCrawled(GbifTerm.GROUP_CRAWLING), 361 362 // Species Profile checklist extension 363 isMarine(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION), 364 isFreshwater(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION), 365 isTerrestrial(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION), 366 isInvasive(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION), 367 isHybrid(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION), 368 isExtinct(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION), 369 livingPeriod(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION, "timePeriod"), 370 ageInDays(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION), 371 sizeInMillimeters(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION, "sizeInMillimeter"), 372 massInGrams(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION, "massInGram", "weightInGram"), 373 lifeForm(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION), 374 375 // Vernacular Name checklist extension 376 organismPart(GbifTerm.GROUP_VERNACULAR_NAME_EXTENSION), 377 isPlural(GbifTerm.GROUP_VERNACULAR_NAME_EXTENSION), 378 isPreferredName(GbifTerm.GROUP_VERNACULAR_NAME_EXTENSION), 379 380 // Distribution checklist extension 381 appendixCITES(GbifTerm.GROUP_SPECIES_DISTRIBUTION_EXTENSION), 382 numberOfOccurrences(GbifTerm.GROUP_SPECIES_DISTRIBUTION_EXTENSION), 383 384 /** Boolean indicating if the publishing country is different to the location country. */ 385 repatriated(DwcTerm.GROUP_OCCURRENCE), 386 387 /** Calculated relative organism quantity, based on organism and sample measure types */ 388 relativeOrganismQuantity(DwcTerm.GROUP_MATERIAL_SAMPLE), 389 390 /** Flag occurrence when associatedSequences/extension exists */ 391 isSequenced(DwcTerm.GROUP_OCCURRENCE), 392 393 /** GBIF region based on country code */ 394 gbifRegion(DwcTerm.GROUP_LOCATION), 395 396 /** GBIF region based on publishing country code */ 397 publishedByGbifRegion(DwcTerm.GROUP_LOCATION), 398 geologicalTime(DwcTerm.GROUP_OCCURRENCE), 399 lithostratigraphy(DwcTerm.GROUP_OCCURRENCE), 400 biostratigraphy(DwcTerm.GROUP_OCCURRENCE), 401 dnaSequenceID(GbifTerm.GROUP_DNA_DERIVED_DATA), 402 403 /** 404 * The <a href="http://rs.tdwg.org/eco/terms/Event">Humboldt</a> extension row type. 405 */ 406 Humboldt(GbifTerm.GROUP_ROW_TYPE); 407 408 private static final String PREFIX = "gbif"; 409 private static final String NS = "http://rs.gbif.org/terms/1.0/"; 410 private static final URI NS_URI = URI.create(NS); 411 412 public static final String GROUP_CRAWLING = "Crawling"; 413 public static final String GROUP_DATASET = "Dataset"; 414 public static final String GROUP_ROW_TYPE = "RowType"; 415 public static final String GROUP_SPECIES_DISTRIBUTION_EXTENSION = "SpeciesDistribution"; 416 public static final String GROUP_SPECIES_PROFILE_EXTENSION = "SpeciesProfile"; 417 public static final String GROUP_VERNACULAR_NAME_EXTENSION = "VernacularName"; 418 public static final String GROUP_DNA_DERIVED_DATA = "DnaDerivedData"; 419 public static final String GROUP_HUMBOLDT = "Humboldt"; 420 421 /** 422 * Lists all GBIF term groups. 423 */ 424 public static final String[] GROUPS = {GROUP_CRAWLING, GROUP_DATASET, DwcTerm.GROUP_OCCURRENCE, GROUP_ROW_TYPE, 425 GROUP_SPECIES_DISTRIBUTION_EXTENSION, GROUP_SPECIES_PROFILE_EXTENSION, DwcTerm.GROUP_TAXON, 426 GROUP_VERNACULAR_NAME_EXTENSION, DwcTerm.GROUP_LOCATION}; 427 428 /** 429 * Lists all GBIF terms in taxon group. 430 */ 431 public static final GbifTerm[] TAXONOMIC_TERMS = 432 {GbifTerm.checklistKey, GbifTerm.taxonKey, GbifTerm.acceptedTaxonKey, GbifTerm.kingdomKey, GbifTerm.phylumKey, 433 GbifTerm.classKey, GbifTerm.orderKey, GbifTerm.superfamilyKey, GbifTerm.familyKey, GbifTerm.subfamilyKey, 434 GbifTerm.tribeKey, GbifTerm.subtribeKey, GbifTerm.genusKey, GbifTerm.subgenusKey, GbifTerm.speciesKey, 435 GbifTerm.species, GbifTerm.canonicalName, GbifTerm.nameType, GbifTerm.acceptedScientificName, 436 GbifTerm.verbatimScientificName, GbifTerm.environments}; 437 438 private final String groupName; 439 private final boolean isDeprecated; 440 public final String[] normAlts; 441 442 GbifTerm(String groupName, String... alternatives) { 443 this.groupName = groupName; 444 this.normAlts = alternatives; 445 boolean deprecatedAnnotationPresent = false; 446 try { 447 deprecatedAnnotationPresent = GbifTerm.class.getField(this.name()).isAnnotationPresent(Deprecated.class); 448 } catch (NoSuchFieldException ignore) { } 449 this.isDeprecated = deprecatedAnnotationPresent; 450 } 451 452 /** 453 * The simple term name without a namespace. 454 * For example taxonKey. 455 * 456 * @return simple term name 457 */ 458 @Override 459 public String simpleName() { 460 return name(); 461 } 462 463 /** 464 * Array of alternative simple names in use for the term. 465 * 466 * @return simple term name 467 */ 468 @Override 469 public String[] alternativeNames() { 470 return normAlts; 471 } 472 473 /** 474 * The optional group the term is grouped in. 475 * For example Occurrence, Taxon, etc. 476 */ 477 public String getGroup() { 478 return groupName; 479 } 480 481 482 /** 483 * List all terms that belong to a given group. 484 * 485 * @param group the group to list terms for 486 * @return the list of GBIF terms in the given group 487 */ 488 public static List<GbifTerm> listByGroup(String group) { 489 List<GbifTerm> terms = new ArrayList<GbifTerm>(); 490 for (GbifTerm t : GbifTerm.values()) { 491 if (t.getGroup().equalsIgnoreCase(group)) { 492 terms.add(t); 493 } 494 } 495 return terms; 496 } 497 498 @Override 499 public String toString() { 500 return prefixedName(); 501 } 502 503 @Override 504 public boolean isClass() { 505 return Character.isUpperCase(simpleName().charAt(0)); 506 } 507 508 @Override 509 public String prefix() { 510 return PREFIX; 511 } 512 513 @Override 514 public URI namespace() { 515 return NS_URI; 516 } 517 518 /** 519 * 520 * @return true if the Term is annotated with @Deprecated. 521 */ 522 public boolean isDeprecated(){ 523 return isDeprecated; 524 } 525 526}