Difference between revisions of "Cache attributes"

From Opencaching.eu
Jump to navigation Jump to search
m (OCPL new ID numbering system, internal and ocgs in sync)
 
Line 39: Line 39:
 
! colspan="5" |<small>Opencaching-DE</small>!! colspan="2" |<small>OKAPI</small>
 
! colspan="5" |<small>Opencaching-DE</small>!! colspan="2" |<small>OKAPI</small>
 
|-
 
|-
!<small>ID<ref group="OC">Opencaching-PL attribute ID. Same as GC attribute ID where applicable.</ref></small>||<small>text_short</small>||<small>text_long</small>||<small>id<ref group="OC">Opencaching-DE internal id</ref></small>||<small>gc_id<ref group="OC" name=":1">Opencaching-DE public id, same as GC attribute ID where applicable.</ref></small>||<small>icon</small>||<small>name</small>||<small>gc_inc<ref group="OC">Opencaching-DE attribute meaning flag, equivalent to GC GPX export. Normal meaning: <code>inc=1</code>; Inverse (negated) meaning: <code>inc=0</code></ref></small>||<small>ACODE</small>||<small>OCGS</small>
+
!<small>ID<ref group="OC">Opencaching-PL attribute ID. Same as GC attribute ID where applicable.</ref></small>||<small>text_short</small>||<small>text_long</small>||<small>id<ref group="OC">Opencaching-DE database contents internal id, not publicly exposed in exports.</ref></small>||<small>gc_id<ref group="OC" name=":1">Opencaching-DE database contents, this exposed publicly in exports as ID for an attribute, numerically the same as GC attribute ID where applicable.</ref></small>||<small>icon</small>||<small>name</small>||<small>gc_inc<ref group="OC">Opencaching-DE attribute meaning flag, equivalent to GC GPX export. Normal meaning: <code>inc=1</code>; Inverse (negated) meaning: <code>inc=0</code></ref></small>||<small>ACODE</small>||<small>OCGS</small>
 
|-
 
|-
 
! colspan="10" |<small>''Common attributes between OC and GC''</small>
 
! colspan="10" |<small>''Common attributes between OC and GC''</small>

Latest revision as of 12:57, 12 August 2019


DRAFT, WORK IN PROGRESS

A geocache may have attached a number of attributes, giving more information about the cache, the hiding, the recommendations, requirements, permissions, hazards, other helpful information related with the search.

This document describes the existing cache attributes across Opencaching sites.


IMPORTANT!!! As of 2019-06-01 the matrix below describes next generation attribute mappings, which is a work in progress implementation.

Attribute numbering rules

  • all OC that have equivalent meaning to a GC attribute to use the same numeric ID; (while the meaning is equivalent, the exact wording of it's name need not be the same. examples are "bring your children / suitable for children / kids friendly / etc");
  • all OC that have equivalent meaning to a negated GC attribute to use the same numeric ID added to 9000. (for example: "available 24/7" is ID 13. "NOT available 24/7" to be ID 9013.);
    • DE branch negated attributes use a separate flag and retain the ID without adding 9000.
  • OC attirbutes that have equivalent meaning on both PL and DE branches and existing DE branch only attributes to retain their IDs in the range 100 - 199;[OC 1]
  • all OC future and existing attributes that are PL branch specific to have numeric IDs in the range 200 - 299;[OC 1]
  • all OC future attributes that are DE branch specific to have numeric IDs in the range 300 - 399;[OC 1]
  • all OC special purpose attributes to have numeric IDs in the range 900 - 999;[OC 1]
  • all OC that have the meaning of a negated OC attribute to use the same numeric ID on the least significant 3 digits, the fourth digit be the branch designator (according to applicability) and the fifth (most significant digit) be 9; (hypothetical generic example: "available during high tide" ID 241 - PL branch (UK), "NOT available during high tide" ID 9241 - PL branch)
  • all attributes have assigned a unique ACODE (according to OKAPI).
  • all "OC only" attributes have assigned a unique OCGS number according to the OCGS numbering rules. (for GPX export purposes by OKAPI and OCDE).

Attributes matrix

OC attributes mapping

Every OC installation has its own set of internal attributes.

Some attributes are common between OC sites; some attributes are common with GC; some attributes are OC only; some attributes are specific to only some OC sites but not all.

OKAPI provides a unified interface for information exchange with third party apps (eg. c:geo) using GC compatibility and OC extensions (GPX export function).

Opencaching-PL Opencaching-DE OKAPI
ID[OC 2] text_short text_long id[OC 3] gc_id[OC 4] icon name gc_inc[OC 5] ACODE OCGS
Common attributes between OC and GC
9001 No dogs Dogs not allowed A85
2 Fee Access or parking fee 36 2 fee Access or parking fee 1 A26
3 Rappeling Climbing gear requried 49 3 rappeling Climbing gear 1 A53
4 Boat Boat required 52 4 boat Watercraft 1 A57
5 Scuba Diving equipment required 51 5 scuba Diving equipment 1 A55
6 Children Suitable for children A70[OC 6]
59 6 kids Suited for children 1 A71[OC 6]
9 Long hike Long walk or hike 25 9 hiking Long walk 1 A21
10 Climbing Some climbing (no gear needed) 28 10 climbing Some climbing (no gear needed) 1 A24
11 Wading Swamp or marsh. May require wading 26 11 wading Swamp, marsh or wading 1 A22
12 Swimming Swimming required 29 12 swimming Swimming required 1 A25
13 Available 24/7 Available 24/7 38 13 Available Available 24 hours 1 A39
9013 NOT available 24/7 Available only during open hours 39 13 time Only available at specified times 0 A40
A73[OC 7]
14 Night Recommended at night A42
9014 Day NOT recommended at night 40 14 day By day only 0 A41
15 Winter Available during winter 44 15 snow Snow-proof hiding place 1 A47
9015 NOT in winter NOT available during winter A84
17 Poison plants Poisonous plants 16 17 plants Poisonous plants 1 A66
18 Dangerous animals Dangerous animals 17 18 Animals Dangerous animals 1 A67
19 Ticks Ticks 14 19 ticks Ticks 1 A64
20 Abandoned mine Abandoned mine(s) 15 20 mine Abandoned mines 1 A65
21 Cliff Cliffs / falling rocks hazard 11 21 cliff Cliff / Rocks 1 A61
22 Hunting Hunting grounds 12 22 hunting Hunting 1 A62
23 Danger Dangerous area 9 23 danger Dangerous area 1 A59
24 Wheelchair accessible Wheelchair accessible A18
25 Parking Parking area nearby 18 25 parking Parking area nearby 1 A33
26 Public transportation Public transportation 19 26 public Public transportation 1 A34
27 Drinking water Drinking water nearby 20 27 water Drinking water nearby 1 A35
28 Restrooms Public restrooms nearby 21 28 restrooms Public restrooms nearby 1 A36
29 Public phone Public phone nearby 22 29 phone Public phone nearby 1 A37
32 Bycicles Bycicles allowed A27
39 Thorns Thorns 13 39 thorn Thorns 1 A63
40 Stealth Stealth required A74
44 Flashlight Flashlight required 48 44 flashlight Flashlight 1 A52
46 Truck / RV Truck / RV allowed A86
47 Field puzzle Puzzle can only be solved on-site 55 47 riddle Puzzle / Mystery 1 A15
48 UV light UV light required A83
51 Special tool Special tool / equipment required 46 51 tools Special equipment 1 A56
52 Night cache Night cache - can only be found at night 1 52 night Only at night 1 A43
53 Car Park and grab 24 53 car Near the parking area 1 A19
54 Ruin Abandoned structure / ruin A82
60 Wireless beacon Wireless beacon / Garmin Chirp™ A9
60 62 calendar Only available during specified seasons 1 A45
9062 All seasons Available all seasons 42 62 date All seasons 0 A44
64 Treeclimbing Tree climbing required A88
OC only attributes
Common attributes between OCPL and OCDE projects
106 OC ONLY OPENCACHING only cache 6 106 oconly Only loggable at Opencaching 1 A1 106
108 Letterbox Letterbox 8 108 letter Letterbox (needs stamp) 1 A4 108
110 Train Active railway nearby 10 110 train Active railway nearby 1 A60 110
123 Firstaid First aid available 23 123 firstaid First aid available 1 A38 123
127 Steep Hilly area 27 127 steep Hilly area 1 A23 127
130 Interestsign Point of interest 30 130 interestsign Point of interest 1 A30 130
131 Moving Moving target 31 131 moving Moving target 1 A11 131
132 Webcam Webcam 32 132 webcam Webcam 1 A12 132
133 Indoor Indoors, withing enclosed space (building, cave, etc) 33 133 indoor Wihin enclosed rooms (caves, buildings etc.) 1 A31 133
134 Under water Under water 34 134 submerged In the water 1 A32 134
135 No GPS No GPS required 35 135 nogps Without GPS (letterboxes, cistes, compass juggling ...) 1 A58 135
137 Overnight Overnight stay necessary 37 137 overnight Overnight stay necessary 1 A69 137
142 Tide Not available during high tide 41 142 tide Not at high water level 1 A48 142
143 Nature Nature preserve / Breeding season 43 143 naturschutz Breeding season / protected nature 1 A46 143
147 Compass Compass required 47 147 compass Compass 1 A49 147
150 Cave Cave equipment required 50 150 cave Cave equipment 1 A54 150
153 Aircraft Aircraft required 53 153 Aircraft Aircraft 1 A75 153
154 Wiki Internet research required 54 154 wiki Investigation 1 A14 154
156 Math problem Mathematical or logical problem 56 156 Arith_prob Arithmetical problem 1 A16 156
157 Othercache Other cache type 57 157 othercache Other cache type 1 A13 157
158 Ask Ask owner for start conditions 58 158 Ask Ask owner for start conditions 1 A17 158
61 161 safari Safari Cache 1 A72 161
OCPL only attributes
201 Quick and easy Quick and easy cache A68 201
202 GeoHotel GeoHotel for trackables A5 202
203 BYOP Bring your own pen A50 203
204 Magnetic Attached using magnet(s) A6 204
205 MP3 Information in MP3 file A7 205
206 Offset cache Container placed at an offset from given coordinates A8 206
207 USB Dead Drop USB container A10 207
208 Benchmark Benchmark - geodetic point A2 208
209 Wherigo Wherigo cartridge to play A3 209
210 Nature Hidden in natural surroundings A28 210
211 Monument Monument or historic site A29 211
212 Shovel Shovel required A51 212
213 Walk Access only by walk A20 213
214 Handicaching Rated on Handicaching.com A76 214
215 Munzee Contains a Munzee A77 215
216 Ads Contains advertising A78 216
217 Military training area Military training area, some access restrictions - check before visit A79 217
218 Video surveillance Caution, area under video surveillance A80 218
219 Trackables Suitable to hold trackables A81 219
220 Historic Officially designated historical monument A87 220
Special purpose attributes[OC 8]
999 Password Log password Password Log Password
  1. 1.0 1.1 1.2 1.3 This assumes that future GC attributes will have their IDs below 100.
  2. Opencaching-PL attribute ID. Same as GC attribute ID where applicable.
  3. Opencaching-DE database contents internal id, not publicly exposed in exports.
  4. Opencaching-DE database contents, this exposed publicly in exports as ID for an attribute, numerically the same as GC attribute ID where applicable.
  5. Opencaching-DE attribute meaning flag, equivalent to GC GPX export. Normal meaning: inc=1; Inverse (negated) meaning: inc=0
  6. 6.0 6.1 While both A70 and A71 map to GC ID 6, Opencaching-PL and Opencaching-DE have slightly different meaning for this attribute, hence the separate ACODES.
  7. Deprecated ACODE (duplicate of A40)
  8. The are not directly user editable attributes, but rather representations for special properties of the cache set by other methods.

Opencaching-PL implementation specific

All attributes are implemented as either ON or OFF; Inverse meaning is handled by a different attribute.

At this time attributes are defined in database (table cache_attrib). Each site has it's own attribute set, hence it's own contents for this table.

Each site must ensure the contents of this table follows the above numbering scheme.

Opencaching-DE implementation specific

Attributes are implemented with a unique internal ID, a separate public ID (same as GC ID where applicable; same as OCGS where applicable) and uses a flag to indicate normal (inc=1) / inverse (inc=0) meaning.

OKAPI implementation specific

OKAPI uses an internal mapping file attribute-definitions.xml.

OKAPI defines an internal ACODE to individually map attributes from each site and also to handle OC to GC equivalence.

OKAPI defines an additional pseudo-Groundspeak ID ("OCGS" IDs) for Opencaching attributes which have no Groundspeak equivalent, used to store such attributes in GPX <groundspeak:attribute> elements. "OCGS" IDs are unique and do not overlap with Groundspeak attribute IDs.

GC reference

Reference documented for establishing equivalences necessary for compatibility with third party apps using GPX file.

  • Attribute has only YES = attribute that can be set or unset;
  • Attribute has both YES and NO = attribute that can be set normally, set as it's inverse meaning or unset;
  1. Not a real attribute (ie. not owner editable for a cache), holds "needs maintenance" flag.
  2. 2.0 2.1 2.2 Special attributes, not available to the regular user.

Developers and site operators

All changes to attributes must follow the rules stated on this page.

Any attribute change must be implemented with the following considerations in mind:

  • documentation here;
  • implementation in the respective Opencaching branch(es), including GPX export module;
  • implementation in OKAPI;
  • notifying third party app developers of the change.

Creating a new attribute

  1. Creating a new attribute must start with submitting an issue on the development page of the respective Opencaching branch(es), as a request for a new attribute.
  2. All new attributes must follow the Attribute numbering rules above.
  3. All new attributes must be properly documented here before implementation. That means inclusion in the Attributes matrix as well as their own descriptive page that will include a deplopyment date.
  4. Developers will then implement the new attribute according to the Opencaching branch(es) involved and OKAPI attribute-definitions.xml.
  5. Third party app developers to be informed of the change.

Adding an existing attribute

A certain Opencaching site may not have an existing attribute from the Attributes matrix.

  1. Document the addition on the attribute's page.
  2. Update OKAPI attribute-definitions.xml.
  3. Deploy the attribute on the site in question according to the procedures for the Opencaching branch software used.
  4. Third party app developers to be informed of the change.

Changing an attribute

Changing an existing attribute's ID must be well justified and follow a procedure similar to that of first removing an attribute then adding a new one.

Changing an existing attribute's meaning or purpose is not permitted.

The only change allowed is updating the attribute's descriptive text (including translations) to better convey it's meaning/purpose for reasons such as bad translation or poor word choice.

Removing an attribute

An attribute may be removed (from use), but not completely deleted, as it will be retained for backwards compatibility.
Exception: when changing the attribute ID according to the above procedure.

A removed attribute will be documented as strike-through text in the Attributes matrix and it's own page.

An attribute may be removed from one site, all sites of a branch or all branches.

  1. Document the removal of the attribute in the Attributes matrix and attribute page including planned removal date.
  2. Update OKAPI attribute-definitions.xml. by removing the relevant site(s). Note: OKAPI forbids the deletion of ACODES even if not mapped to any site, for backwards compatibility reasons.
  3. Remove the attribute usage from the site(s) database according to the procedures for the Opencaching branch software used.
  4. Create an issue on the development page of the respective Opencaching branch(es) to remove the attribute if applicable.
  5. Developers will then implement the change.