Closed GoogleCodeExporter closed 9 years ago
(attributes of caches, like night-cache)
Original comment by o.di...@arcor.de
on 30 Aug 2011 at 11:28
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.
Original comment by rygielski
on 30 Aug 2011 at 11:50
[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).
Original comment by o.di...@arcor.de
on 30 Aug 2011 at 12:10
> 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.
Original comment by rygielski
on 30 Aug 2011 at 12:22
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!
Original comment by o.di...@arcor.de
on 30 Aug 2011 at 3:41
> 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.
Original comment by rygielski
on 30 Aug 2011 at 5:39
But I won't argue about it ;) Your idea might be a good one too. I tend to be
overly cautious.
Original comment by rygielski
on 30 Aug 2011 at 5:48
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.
Original comment by rygielski
on 8 Sep 2011 at 9:17
I will come back to this issue when there will be more OKAPI installations.
Original comment by rygielski
on 8 Sep 2011 at 9:29
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).
Original comment by rygielski
on 28 Jan 2012 at 2:41
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.
Original comment by rygielski
on 1 Feb 2012 at 2:23
BTW, I changed the above URLs to /okapi/devel/attrlist.
Original comment by rygielski
on 26 Mar 2012 at 1:51
Original comment by rygielski
on 23 Aug 2012 at 9:30
> 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.
Original comment by rygielski
on 29 Dec 2012 at 11:32
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.
Original comment by rygielski
on 30 Dec 2012 at 12:02
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 )
Original comment by rygielski
on 30 Dec 2012 at 12:08
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.
Original comment by rygielski
on 30 Dec 2012 at 12:12
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 :)
Original comment by goo...@alweb.dk
on 30 Dec 2012 at 1:23
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.
Original comment by rygielski
on 30 Dec 2012 at 8:06
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)
Original comment by goo...@alweb.dk
on 30 Dec 2012 at 1:05
Original comment by rygielski
on 15 Jan 2013 at 2:36
#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.
Original comment by following09
on 20 Mar 2013 at 8:26
[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.
Original comment by following09
on 20 Mar 2013 at 8:33
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?
Original comment by rygielski
on 25 Mar 2013 at 10:39
ad 1: Yes - it will be not accessible as long as it is not matched to a global
attribute. This is only temporarily, as new local attributes will be registered
as soon as possible with OKAPI, a new entry to the global attrib table will be
added if necessary, and the attribute will become visible with the next OKAPI
update.
ad 2: Yes.
Original comment by following09
on 27 Mar 2013 at 4:30
Original comment by following09
on 27 Mar 2013 at 4:32
ad 1: This conflicts with your commits in #190 (you made internal IDs visible
via geocache method and GPX files).
ad 2:
Usually, OKAPI does not modify "external database scope". I have a different
idea. Instead of trying to keep all databases up-to-date, lets keep an
up-to-date mapping in the repository.
This would be similar to the way OKAPI updates installation lists. All OKAPI
installations periodically check the repository and download the current data
from
https://code.google.com/p/opencaching-api/source/browse/trunk/etc/installations.
xml
I would like the global attribute IDs updated the same way.
I will try to commit it soon.
Original comment by rygielski
on 28 Mar 2013 at 8:15
GPX attributes are a compatibility issue - the internal IDs are already visible
in GPX files downloaded from OC.de and OC.nl. For new featues I agree that this
should be avoided.
> Instead of trying to keep all databases up-to-date, lets keep an up-to-date
mapping in the repository.
So the OKAPI installations would poll this mapping table, store the mapping for
local to global attributes in some okapi_ table and use this okapi_ table to
translate IDs? Sounds fine. :-)
Original comment by following09
on 28 Mar 2013 at 8:58
See here:
https://code.google.com/p/opencaching-api/source/browse/trunk/etc/attributes.xml
?spec=svn588&r=588
This is only a stub, but it shows the general idea.
I am still thinking on the format of okapi_attr_id (which will be the primary
unique key for attributes in OKAPI). Should it be a string, a number or an
uuid? A short descriptive string is user-friendly, but is it
backward-compatible enough?
Backward-compatibility is much more important in this case. For example, what
happens is someone commits an okapi_attr_id with a spelling mistake?
Original comment by rygielski
on 28 Mar 2013 at 10:27
I think we won't need the yes/no option:
OC nodes know only 1-state attributes - if the negation is needed, a second
attribute is used (and OC.de still has the bug to allow contradicting
attributes in the same cache listing :-).
GS uses only the positive attribute names in combination with the
include/exclude flag.
Original comment by following09
on 28 Mar 2013 at 10:36
Do you mean something like this?
https://code.google.com/p/opencaching-api/source/diff?spec=svn589&r=589&format=s
ide&path=/trunk/etc/attributes.xml
Original comment by rygielski
on 28 Mar 2013 at 10:53
Yes.
There are only few of these complementary attributes - on OC.de they are:
- Only at night / by day only
- Available 24 hours / Only available at specified times
- All seasons / Only available during specified seasons
I am thinking about a fourth one as complement to "Snow-proof hiding places".
Original comment by following09
on 28 Mar 2013 at 11:10
Uff. It's a little boring work, but I moved all the attributes from OCPL into
the XML file. Now you can extend the file with OCDE attributes. I will work on
the methods.
https://code.google.com/p/opencaching-api/source/browse/trunk/etc/attributes.xml
Original comment by rygielski
on 29 Mar 2013 at 11:15
BTW, OpenCaching.com resigned from "open tags", they now have a restictive
subset of allowed tags, just as GC anc OC:
https://forums.opencaching.com/showthread.php?557-Taging-Improvements
Original comment by rygielski
on 29 Mar 2013 at 11:38
Still, I think their Garmin devices will display any tags found in the GPX
file, so the ox: namespace seems a good place to store out internal (non-GC)
attributes.
Original comment by rygielski
on 29 Mar 2013 at 11:39
out->our
Original comment by rygielski
on 29 Mar 2013 at 11:40
> Uff. It's a little boring work, but I moved all the attributes from OCPL into
the
> XML file. Now you can extend the file with OCDE attributes. I will work on
the
methods.
Great! I will immediately do that and add Spanish and Italian translations,
too. I would also like to add a 'name' attribute to the 'groundspeak' element,
so that we can output the exact GS attribute names in GPX files.
Original comment by following09
on 29 Mar 2013 at 11:43
I also add english description texts for OC.de attributes.
Original comment by following09
on 29 Mar 2013 at 12:04
> I would also like to add a 'name' attribute to the 'groundspeak' element
Okay.
Original comment by rygielski
on 29 Mar 2013 at 12:15
This issue was updated by revision r592.
Original comment by rygielski
on 29 Mar 2013 at 3:33
Also, r593 may help you with your work.
Original comment by rygielski
on 29 Mar 2013 at 3:37
Ok.
I have grouped attributes into the following categories (just ordered in the
file) to make it clearer:
- listing
- cache types
- preconditions
- accessibility, way
- location
- facilities
- time and seasons
- tools required
- dangers
- rating
This breaks with the current OC.de grouping scheme, which is suboptimal. I
suggest to add the grouping scheme to the OKAPI database and make it accessible
to clients, so that they can display attributes in some order.
This is where I am, will take some more hours to complete:
http://www.neverwhere.de/attributes.xml
Will proof read and XML-syntaxcheck when finished.
Original comment by following09
on 29 Mar 2013 at 3:57
> I suggest to add the grouping scheme to the OKAPI database and make
> it accessible to clients, so that they can display attributes in
> some order.
I also thought about it, but I decided to think about it later, after
we get it running. I also thought about adding OKAPI attribute icons,
but this be lots of work.
Original comment by rygielski
on 29 Mar 2013 at 4:26
This issue was updated by revision r595.
Original comment by following09
on 29 Mar 2013 at 7:58
I think that both of our nodes have much too many attributes (and many of them
seem quite... well... stupid). When there are so many attributes, they start to
loose their meaning, because users don't even know they exist.
It seems to me that Groundspeak's attributes are much more useful that OCPL's
and OCDE's. But I guess it's not for me to judge, this would require an open
discussion with many, many people... :(
In this case, I should also re-add some of the OCPL attributes which I have
initially skipped, because I thought they were bad.
Original comment by rygielski
on 29 Mar 2013 at 11:17
On the other hand, if you agree that most of the attributes are unnecessary and
should be removed, we could simply ignore such attributes in OKAPI. We could
also merge some of the attributes into other, more general attributes. What do
you think?
Original comment by rygielski
on 29 Mar 2013 at 11:18
> It seems to me that Groundspeak's attributes are much more useful that OCPL's
and OCDE's.
Groundspeak has lots of bullshit attributes like "dogs allowed" and "bicycles
allowed" and "horses allowed" and "stroller accessible" and "wheelchair
accessible" (actually OC.pl some two of these, too ;-). What wheelchair and
wheelchair user is meant here? The fubar one who cannot move his chair by
himself and just grab things in 50 cm distance? Or the sportive one who drives
offroad and can grab things on the ground or in 150cm height? And how many
cache owners are able to estimate what a wheelchair driver is able to do at
all? On GC, the "wheelchair attribute" generally is used synonyme to "Terrain
1.0". Which makes it redundant to terrain rating.
What bicycle is meant? Racing? Touring? Mountain? If the cache lies in a
pedestrian area where you must not bike but have to shove the bike for a few
meters, does this mean that "bikes prohibited" must be set? And of what use
will it be if "bikes prohibited" is set for the cache? None at all.
Dogs are prohibited on playgrounds. But I may leash my dog at the playground
entrance, grab the cache and pick up my dog. Must I set the "dogs prohibited"
here? And of what use would it be? None. There may be bad-trained dogs which
cannot be leashed and left alone. So the only sensible thing here is to state
in the cache description that it's a playground. Then the onwners can decide
what to do.
And so on ...
> I think that both of our nodes have much too many attributes
Attributes serve two different purposes:
- searching / selecting caches
- replacing parts of the text description by handy and faster-to-grab icons
E.g., it does not make sense to search for "posion plants" or for "special tool
required". Also, it does not make sense to search for "no posion plants" or "no
special tool required", because attributes are missing in many listings, so
abcense of "poison plants" attribute does NOT mean that there are no posion
plants. It even does not make sense to introduce a "no poison plants"
attribute, because it could have very bad consequences if an owner sets it in
error. So these two attributes always are just part of the cache description -
replacement icons for writing "beware of poison plants" or "attention, you need
the following tools:".
(Actually, OC.de allows all those kind of nonsense searches. It is somewhere
medium-prio on my todo list to fix this).
ALL of the attributes I listed in attributes.xml are in use on OC.de, and many
owners rely on that they are displayed (I never saw someone writing "beware of
ticks" in the text when the ticks attrib is set!) So eliminating attributes
means eliminating parts of the cache description, which I don't think is a good
idea.
But I think it would be a good idea to distinguish between "searchable" and
"not searchable" attributes.
Original comment by following09
on 30 Mar 2013 at 12:34
Btw, GC has more attributes than OC.de, even if you count the positive/negative
attributes only once.
Original comment by following09
on 30 Mar 2013 at 1:38
Original issue reported on code.google.com by
o.di...@arcor.de
on 30 Aug 2011 at 11:27