(attributes of caches, like night-cache)

Almost certainly I won't have the time to do this. Maybe some other developer 
will feel like it.

Some notes on this subject:

OKAPI is about integrating all OpenCaching sites. Each OpenCaching site has 
various attributes. In order to get it right, all of these attributes must be 
*mapped* to *one* set of attribute names, *stored within OKAPI*. I think this 
should be done in a similar way I did the "log types" and "cache types" i.e. 
some attributes will be "globally recognized" and supported by OKAPI, others 
will not.

[deleted comment]

Maybe we can work with meta-functions:

GetAvailableCacheAttributes() returns array of AttributeDefinition. The array 
will contain all attributes known by that OC node.

AttributeDefinition contains:

internal_id - internal identifier of the attribute. Maybe interger or string
localized name - name of the attribute in requested language
localized description - html-snippet explaining what the attribute means
icon_url - http-url of the icon with a size of maximum X x Y pixels. Plus url 
of grayed-icon and unselected icon
uuid - if the attribute is known on several nodes, the uuid will be the same. 
Images and specific description may differ, but meaning of the attribute is the 
same.

This way, the OC node admins can easily define uuid of matching attributes and 
use that uuid for attributes that are newly introduced. OKAPI does not need to 
know these uuid at all. But the application developer is able to search for 
night caches at oc.pl and oc.de at once.

The return value of GetAvailableCacheAttributes() could be easily built from 
table cache_attributes (i am not sure about oc.pl, but i think they also have 
this table).

> Maybe we can work with meta-functions:
>
> GetAvailableCacheAttributes() returns array of AttributeDefinition

Maybe. But this approach has numerous disadvantages. Keep in mind,
that there will be applications that will want to support multiple
OKAPI servers in the same time. Such applications would have to keep
multiple sets of attributes instead of one. Messed up!

> Images and specific description may differ, but meaning of the
> attribute is the same.

Let's say I'm an external developer. If I wanted to access multiple
OKAPI installation, I would have to connect each of them, get their
attributes, then merge them in some way, keep them synchronized and
watch out NOT to call attribute X on node Y, because node Y does not
support X. Messed up! I would think this kind of merging work should
be done by OC developers, not me, an external developer.

That's way in think its better if every OKAPI installation comes with
a predefined set of attributes. All OC nodes should work out this set,
merge it an cooperate.

Yes, you are right. It is more work for external developers. But i dont think 
it is that much of work.

As of my experience with various OC nodes, we have the situation that some 
nodes have local modifications that are not covered by the other nodes. And we 
are not able to do synchronous update OC source on all nodes. If one node wants 
to have a new attribute or cache type, they wont wait for all other nodes to 
commit on that or update their sources.

But if you get all OC node admins together to discuss about that problems, i 
will support you!

> As of my experience with various OC nodes, we have the situation
> that some nodes have local modifications that are not covered by the
> other nodes. And we are not able to do synchronous update OC source
> on all nodes.

But you don't need to update OC sources. If you design OKAPI methods
in a permissive way, they can work with all types of known attributes
and simply ignore unknown ones. Or even - during the update* - send
YOU an email about all detected unknown attributes. This way, you will
be able to add them to a new revision.

* - by "update" I mean the script admins are to execute after
installing new OKAPI revision. This script can search for unknown
attributes and report on them.

> If one node wants to have a new attribute or cache type, they wont
> wait for all other nodes to commit on that or update their sources.

Such unknown attributes could be simply ignored by OKAPI. This would
also give node admins a reason to notify you about their new
attribute. (Provided, all local OKAPI modifications are *offically
forbidden*.)

> But if you get all OC node admins together to discuss about that
> problems, i will support you!

I don't think you have to. If they want to use OKAPI, they will come
to you by themselves and ask you to add an attribute. You could
include specific instructions to contact you in key places of OKAPI
code.

But I won't argue about it ;) Your idea might be a good one too. I tend to be 
overly cautious.

This issue was updated by revision r141.


Some basic support for attributes was added to "geocaches" and "gpx" methods. 
Only names of attributes are returned. When (if?) OC node attributes will 
include UUID fields, it will be possible to extend this.

I will come back to this issue when there will be more OKAPI installations.

Some notes on this:

OpenCaching.com has introduced tags, which are basically the same as our 
attributes. They decided to allow users to create tags of their own, freely. 
This means that OpenCaching.com already has hundreds or thousands of different 
tag names in different languages and they seem to think it's okay.

Maybe they do have a point? Maybe the identifier of the attribute should be the 
name of the attribute itself? This doen't seem "international", but it is 
just... easy. And I think this is the only option left for us (given the number 
of attributes present in different OC sites).

Once all OC installations have OKAPI, we will be able to collect all different 
attribute names with a simple (hidden) method, like this one:

http://www.opencaching.org.uk/okapi/attrlist
http://www.opencaching.pl/okapi/attrlist
http://www.opencaching.us/okapi/attrlist

Once we can collect them, we may attempt to create a global table of attributes 
with all possible translations. This table would be periodically read by all 
OKAPI installations. All OKAPI installations would be able to return attributes 
in all languages.

I am not sure if this is the right way to go, but it is still available.

BTW, I changed the above URLs to /okapi/devel/attrlist.

> Comment #10 on issue 19 by goo...@alweb.dk: General discussion on  
> the "services/caches/geocache" method.
> http://code.google.com/p/opencaching-api/issues/detail?id=19

> Another comment about attributes: If all I can get to identify them are
> their "names" (I get strings like "Go geocaching with children"), I need to
> make an extra request to get the english names to be able to map them to a
> graphic in case I have users using a different language that the service
> knows (polish for opencaching.pl etc).

> To support multiple okapi services, I create a special OkapiService  
> opbject, holding the base URL and my authorification keys for the service,
> and the users when logged in. I plan to have a map of string => graphic
> there for attributes to overcome the differences, but at this point that
> will not help wrt the language problem.
> I suggest maybe a short, language independant but site specific identifier
> string?


> Comment #11 on issue 19 by rygielski: General discussion on  
> the "services/caches/geocache" method.
> http://code.google.com/p/opencaching-api/issues/detail?id=19

> Currently, there is no such list. The reason for this is, the attribute set
> is different for every OC node. Also, often *different sites name the same
> attribute in a different way*. They also keep adding new attributes and
> there is no one "central" way of coordinating this. I plan on making this
> list unified before publishing it via OKAPI. Unfortunatelly, such  
> unification is not possible until OpenCaching.DE starts using OKAPI. See
> issue 70.

> Regarding images: I am not sure about exporting attribute images via OKAPI.
> Primarily because, to be honest, I find most of them ugly. The same goes
> for cache type images, log type images and many other images. Regarding
> such things, I think it best for OKAPI to stay plain-text-only. But I am
> open to discussion.

> Let's continue this discussion in issue 70.

My current idea for "unification" is a little complex, but I cannot think of 
any better one:

1. Every OC node may have its own attributes. Just as it did before. It may add 
them, change them, etc.

For example:
OCPL: "Only at night", "Quick cache", "Compass needed".
OCDE: "Night cache", "One-minute cache".
OCORGUK: "Night-cache", "Quick-cache", "Take a compass".

2. OKAPI may TRY to make the names unified by holding a simple mapping file in 
the repository. For example:

{
"Only at night": "Night-cache",
"Night cache": "Night-cache",
"One-minute cache": "Quick-cache",
"Take a compass": "Compass needed",
}
# Let's say "Quick cache": "Quick-cache" is missing here.

Having such mapping, OKAPI may try to translate attributes names to one common 
name. Such name MAY become a unique attribute ID (or we may create a GUID for 
that).

3. The example output, after being mapped through OKAPI would give us:

{
OCPL: "Night-cache", "Quick cache", "Compass needed".
OCDE: "Night-cache", "Quick-cache".
OCORGUK: "Night-cache", "Quick-cache", "Compass needed".
}

OKAPI could automatically detect new attributes added and ask the admins to 
include them in our "unified" mapping.

The mapping above is a simple example. In practice, this would have to be a 
more complex XML document, with various languages, guids etc.

The alternative is to merge all various attrnames together, as proposed in 
comment#11.

The simple "merge everything" approach would be much easier for me, but it 
would also make "searching by attributes" much harder for external developers 
(because each site would have its own set of attributes, some of which don't 
even HAVE an English name - like these on the bottom here: 
http://www.opencaching.nl/okapi/devel/attrlist )

If we choose to give a GUID for "unified" attributes, we would have to 
differentiate between "unified" and "local" attributes in all the methods. For 
example, "searching by attribute" would be possible using only the "unified" 
ones, but all the "local" ones would still need to be included in the cache 
description.

Well, as you can see, all this kinda sucks.

I want to add a comment from an app-developers pov.

I query currently OCPL, and want to use attributes, represented by graphics.
My problems with this are
1) I can't get a list of known values. I collected the following list, but I 
can't know if it is complete (taken from my code mapping to image names):
        attributeMap["Access only by walk"] = "walk";
        attributeMap["Accessible for disabled"] = "disabled";
        attributeMap["Bike"] = "bike";
        attributeMap["Compass"] = "compass";
        attributeMap["Dangerous cache"] = "danger";
        attributeMap["Fixed by magnet"] = "magnet";
        attributeMap["Go geocaching with children"] = "children";
        attributeMap["Monumental place"] = "monument";
        attributeMap["Nature"] = "nature";
        attributeMap["Offset cache"] = "offset";
        attributeMap["One-minute cache"] = "fast";
        attributeMap["Periodic/Paid"] = "period";
        attributeMap["Recommended at night"] = "night";
        attributeMap["Take something to write"] = "pencil";
        attributeMap["Take special equipment"] = "equip";
        attributeMap["Torch needed"] = "torch";
        attributeMap["You will need a shovel"] = "dig";
//         attributeMap[""] = "";
//         attributeMap[""] = "geohotel";
//         attributeMap[""] = "gpsfree";
//         attributeMap[""] = "password";

(As you can see, I did not meet any caches using the geohotel, gpsfree or 
password attributes so far, but I found the graphics in your wiki.)

A list would be very cool!

2) I read in the api docs that the list might be different for different OC 
sites, so when I get to make my app multi-site, I will have to compile a list 
for each new site I enable.

3) The strings I get are in english, but that is just luck - to be sure, I have 
to send an extra query with langpref set to "en", since I may have users using 
polish (or dutch or swedich or german), which may disturb my current code 
because the attribute names may come in those languages afaics. I use the 
attribute names as a tooltip for the graphics, so I may need to do some extra 
work to pick the native-language string for that.

This is pretty bad, having a id code - a string suitable for a graphic file 
name would be good - would be very much better! I don't see why that would be 
bad. An example:

{"attributes":[{"name":"Torch required";"id":"torch"},{"name":"You will need a 
shovel";"id":"shovel"}]

You get the idea. This would make my life a lot easier :-)

4) Syntax. The names are very unequal, for example "Torch required" vs "You 
will need a shovel". Some strings are very informative, others completely not 
so (like "Compass").

Using an id string would allow to change this text as needed and to add new 
translations withouth disturbing clients.

Thanks for your time :)

The key point is, each site has different IDs. If users wanted to find
a "night-cache" in *all* OKAPI servers, there simply wouldn't be any
way for you to implement this without knowing the ID of a
"night-cache" in all these servers. Therefore, you would have to make
your user *first* choose which OKAPI server to use, and *then* display
the attributes, which is - I think - a bad idea. I think the best
approach would be in all OKAPI servers could understand a one, common
set of attributes. That's why I thought it better to not implement it
at all, until we think of any better way.

I understand your problems, but currently there is no quick way I
could fix this. I could export attribute names from a single OC node,
but forcing app developers to use a different attribute set per each
OKAPI server is not "good enough" for me. Also, OCDE may have a
different attribute system - until they begin to use OKAPI, we cannot
be sure that this interface will be compatibile with their model.

Last time I checked, OCDE planned to introduce OKAPI just after the
New Year.

While I appreciate the idealism, in this case I am mostly pragmatic. My 
conclusion is to stop trying to add support for attributes in my application 
for now, since the OKAPI does not provide support. I will revisit this subject 
when there is a development.

Meanwhile, I think that all you need is an id string, and a listing of all such 
ids with descriptions. If you can not convince all the sites using the API to 
agree on a common list, it is better to allow individual lists than not dealing 
with the issue, because then app developers can not provide users with nice 
representation of attributes at all.

Kindly. Anders (who, btw, thinks OKAPI is very, very nice to work with in 
general)

#5:
> That's way in think its better if every OKAPI installation comes with
> a predefined set of attributes. All OC nodes should work out this set,
> merge it an cooperate.

#7:
> If you design OKAPI methods
> in a permissive way, they can work with all types of known attributes
> and simply ignore unknown ones. Or even - during the update* - send
> YOU an email about all detected unknown attributes. This way, you will
> be able to add them to a new revision.

I think this is a good solution and am ready to support it for OC.de. We need a 
list of well-defined attributes within OKAPI, and an additional global_id 
column in the local attribute tables. The all attributes that have a known 
global ID (I suggest english names here instead of unreadable things) are 
returned by OKAPI, i.e. a list of the IDs is returned. With an additional 
method, the client can then request the node-specific informations on these 
attributes that Oliver listed in post #4: localized name and description 
(according to langpref; node's default language if unknown) and icons. I think 
local IDs are irrelevant.

Now, this must be coordinated between nodes. I think it's hopeless they will do 
it on their own. Therefore, if you are ready to support this concept, I could 
assume the task of collecting attribute informations from the nodes and compile 
an initial list of well-known attributes with mapping to local IDs. You could 
include this list in an OKAPI update and intialize the global_id fields in the 
nodes' attribute tables. Then it would be your task to add new or changed 
attributes to the list of well-known attributes on request by the nodes, i.e. 
to decide for each request if the local attribute can be matched to an existing 
global ID, or if you add a new one for it.

[deleted comment]

With "a list of IDs is returned" I meant the geocaches method, that returns 
attributes of a cache. It als would make sense that the client can request a 
list of all "global attributes" supported by a node.

I'm not sure if I understood correctly.

1. You want only "global" attributes visible via OKAPI. Attributes with 
global_id set to null will not be accessible.

2. You'd like OKAPI to set the global_id in every server automatically, based 
on the current values mentioned in comment 12?

Probably I won't modify the docs much today.

I think that the word "deprecated" for no-longer-used attributes is wrong. 
"Deprecated" is something which still can be used, but should no longer be 
used. Thatt would be attributes which still can be added to cache listings, 
though it is recommended not to do so. Or which can be present in attr_acodes 
but should be ignored.

"Discontinued" would fit it better. 

I also thought about it for a while, but ended up in conclusion that it doesn't 
really matter. In fact, we cannot force an attribute to stop being used - some 
OKAPI installations are not upgraded often (OCORGUK wasn't upgraded for a year, 
I believe!), also the deprecated attributes may be included in old files, etc. 
AND - it we allow searching by A-codes - it will be also allowed (though the 
result will be empty). So, "deprecated" kinda fits too.

You may update the descriptions if you want, but let's leave the name as it is.

> In fact, we cannot force an attribute to stop being used

Right. And I think we don't WANT the OKAPI users to stop using it, but they 
still should evaluate and display it if it appears in some older- oder 
newer-version data.


"is_deprecated - boolean, indicates if the attribute has been discontinued. It 
probably will not appear in geocaches attr_codes fields of data retrieved from 
this OC node and from other up-to-date nodes, though it may still be present at 
nodes which run older OKAPI versions. Also, it may be re-introduced in upcoming 
OKAPI versions, which may happen in the very moment when you retrieved this 
information; so there is a slight chance that the attribute WILL be present in 
your next geocache query from this OC node, because it has just been 
re-introduced.

Please note that the attribute is NOT deprecated: If you encounter it in some 
data from other OKAPI versions, you are encouraged to evaluate and display it."

No, that's not being deprecated means. It *is* deprecated, because we don't 
want other OC sites and cache-owners to use it for new caches, etc. However, it 
may still appear in older GPX files and non-updated OKAPI installations, so 
external developers *have to* expect it, even when it's deprecated.

[deleted comment]

Well, then I would like to deprecate the "bicycles allowed" and "wheelchair 
accessible" attributes: OC.pl owners should no longer use them in their caches, 
because they are bullshit. ;-)

Sorry, I don't understand you :( These two are used and there is nothing we can 
do about it either...

[deleted comment]

I tried to show you that your statement "It *is* deprecated, because we don't 
want other OC sites and cache-owners to use it for new caches, etc" does not 
make sense. We cannot deprecate things which happen outside of OKAPI.

"Deprecated" means: "You can use it, but we recommend not to do so." So: 
*where* can A42 - after it has been taken out of service - still be used in a 
meaningful way but should not be used?

You misunderstood me. By "we" I meant all OC admins - we can deprecate an 
attribute ONLY when all OC nodes choose to do it. When a node doesn't update 
its OKAPI, the process of "being mark as deprecated" will be delayed at this 
site, but we can still say that ALL OC nodes find the attribute deprecated.

Deprecated means (it's out of a dictionary): "To mark (a component of a 
software standard) as obsolete to warn against its use in the future so that it 
may be phased out."

> *where* can A42 - after it has been taken out of service - still be used in a 
meaningful way but should not be used?

For example, in search queries (if we decide we want to allow searching by 
A-codes).

Afaik OC nodes never deprecated attributes, and I think they never will. They 
may decide to remove attributes from their database, or not to allow them to be 
added to cache listings (OC.de has two such "historic" attributes, which are 
marked with the 'search_default=0' flag and ignored by OKAPI), but that's not 
deprecation as the users have no choice to use them.

> To mark (a component of a software standard) as obsolete to warn against its 
use in the future so that it may be phased out.

Precisely. The software component is still present, it does still work in the 
way as it worked before, but nevertheless it should no longer be used for some 
reason - see geocaches.size and geocaches.hint.

This is NOT true when searching for an A-code which is no longer connected to a 
local attribute. The search will no longer work, because the attribute is not 
just deprecated but DEAD on the OC installation which says it "is deprecated". 
And old OKAPI installations where it would make sense to deprecate it will keep 
telling it "is not deprecated".

For me this is all confusing and misleading, but anyway I am happy about the 
attributes implementation, and this is just a small flaw which I can well live 
with - developers should be able to figure out what is meant.

To avoid more misundestanding: 

> The search will no longer work

The search will do something, but it will no longer return caches with that 
property (i.e. Night Caches when searching for A42). The function "search night 
caches via A42" is dead.

> The software component is still present, it does still work in the
> way as it worked before

Yeap, and the "search for a deprecated attribute" will still work. 
That is, it won't raise HTTP 400 or something like that.

> This is NOT true when searching for an A-code which is no longer
> connected to a local attribute. The search will no longer work,

But you could say that for any non-locally-supported *non-deprecated*
attribute too. There is a difference between being globally deprecated
and being non-local.

> And old OKAPI installations where it would make sense to deprecate
> it will keep telling it "is not deprecated".

Yes, that's a problem. Hence the notion (in the docs) that the
developers should use one of the often updated OKAPI installations
if the want the most up-to-date attribute data.

> For me this is all confusing and misleading

It would still be confusing, regardless how we named this attribute...
Attribute-unification is a mess. :(

> developers should be able to figure out what is meant.

I hope so too... I am a little surprised you don't like the usage
of the word "deprecated" in this context. I tried to understand your
arguments, but I can't :(

I am sorry that I cannot explain it better, and I have no doubt that 
"discontinued" would have been less confusing. Looks like inspite of the 
dictionary entry, we have different undestandings of what "deprecated" means.

How about is_globally_used?

Or even "is_used"?

I think both would be misleading, because the flag may by "false" while the 
attribute is still or again in use at OC nodes with other OKAPI versions.

One more thought on "deprecated". I think this term is correct regarding 
installation of old OKAPI revisions: We advise OC nodes to upgrate to a current 
OKAPI which does no longer use this attribute - it's the old OKAPI versions 
which are deprecated! But the docs are intended for users, not for OC admins. 
Users have no choice of OKAPI versions.

positive:
is_active
is_supported

negative:
is_phased_out
is_discontinued

'discontinued' is still my favorite, it fits very well. dict.cc give a good 
understanding of this; unfortunately the explanations are in German only, but 
the synonymes are also interesting: http://www.dict.cc/?s=discontinued

"discontinued items / lines / models" -> goods which are no longer produced but 
may still be in stock and sold

"discontinued" in industrial context = German "abgekündigt" = We won't produce 
this any more, but it may still be available somehow.

> I think both would be misleading, because the flag may by "false"
> while the attribute is still or again in use at OC nodes with other
> OKAPI versions.

That's also the case for "is_discontinued". It can be "true" on some 
OC nodes while it can be "re-continued" on the newer ones. Also 
"is_used" would match "is_locally_used" more closely.

But I don't really care how it's named, as far as it's documentation
is clear. I renamed "is_deprecated" to "is_discontinued", perhaps
you're right that "deprecated" was not exactly what it was.

I also removed the "include_deprecated" parameter from
attribute_index, as it might be dangerous for non-aware developers.
Now, discontinued attributes will always be included, when a developer
asks for all attributes. It is much safer this way, at least for now.

Thanks for renaming the field. The description

"true means that, as far as *this* OKAPI version "knows", *none* of the OC 
servers is currently using it (geocaches are no longer tagged with this 
attribute)"

is wrong: The attribute may still be returned by other OC serves with old OKAPI 
revision. E.g. if you remove A42 at OC.pl and return A43 instead for local ID 
91, OC.de will still return A42 for local ID 1 as long as it has not been 
updated to a new OKAPI revision.

I have fixed this.

> E.g. if you remove A42 at OC.pl and return A43 instead for local ID 91, OC.de 
will still return A42 for local ID 1 as long as it has not been updated to a 
new OKAPI revision.

That was wrong too, sry - OC.de always returns A43 for ID 1. But if there were 
another site running OCPL code which is not updated, *that* site would continue 
to output A42 for local ID 91.

Sry, the docs where not "wrong" but covered just the first of these three cases:

Case 1: A-Code is discontinued because all corresponding local attributes have 
disappeared. Then it is true that no OC server is using this A-code any longer. 
This never happened and should never happen at OCDE, but maybe OC.pl will 
finally get rid off that bicycle thing. ;)

Case 2: A-Code is discontinued because all corresponding local attributes have 
been re-mapped to other A-Codes. Then the A-Code can still be in use at servers 
with older OKAPI revisions. See A42/A43.

Case 3: A-Code is discontinued because all corresponding local attributes are 
obsolete and therefore no longer included in OKAPI, while they are still 
present in some old cache listings. E.g. attributes like "needs aircaft" at 
OC.de which turned out to be useless and therefore is neither included in OC.de 
search functions nor in OKAPI, but still is included in some active listings 
(because we never manipulate existing listings.)

Maybe I missed some more cases.

That's too complicated to explain in the docs, but it might make sense to point 
from is_discontinued to to here for further explanation.

This attribute topic is brain-twisting, my brain really needs some time to 
un-twist now. :-/

> I have fixed this.

But "This means that it is no longer in use at OC servers which run current 
OKAPI versions" also needs not to be true, as *this* server may run an outdated 
OKAPI version ...

Keeping the Attribute definitions in a central repository would avoid this 
complexity - then the discontinued attibutes would really disappear from *all* 
OKAPI installations quickly, and it would be reasonably safe for an application 
to ignore discontinued attributes.

But you probably had good reasions to move it into the code distribution.

The idea with central repository and automatic updates is cool, but gets 
complicated as we change things. And currently, we change things a lot.

I seems a safer option, for now. The implementation is simpler, and I'm a 
little tired of all this complexity...