Document a convention for using Links to define tags on Collections.

diff --git a/doc/api/schema/Link.textile b/doc/api/schema/Link.textile
index ed8271dafdaa043db3d96f3f93616b88fe98c356..6156414301a6517282ff31218939f81a48759d53 100644 (file)
--- a/doc/api/schema/Link.textile
+++ b/doc/api/schema/Link.textile
@@ -8,12 +8,21 @@ navorder: 12
 
 h1. Link
 
-Links encode connections between Arvados objects, and from objects to primitives.  Each metadata object has a tail (subject), class, name, properties, and head (object or value).
+**Links** describe relationships between Arvados objects, and from
+objects to primitives.
 
-table(table table-bordered table-condensed).
-|tail (object)| _class, name_ 
-→
- _properties{}_ |head (object)|
+Links are directional: each metadata object has a tail (subject),
+class, name, properties, and head (object or value).  A Link may
+describe a relationship between two objects in an Arvados database:
+e.g. a _permission_ link between a User and a Group defines the
+permissions that User has to read or modify the Group.  Other Links
+simply represent metadata for a single object, e.g. the _identifier_
+Link, in which the _name_ property represents a human-readable
+identifier for the object at the link's head.
+
+For links that don't make sense to share between API clients, a
+_link_class_ that begins with @client@ (like @client.my_app_id@ or
+@client.my_app_id.anythinghere@) should be used.
 
 h2. Methods
 
@@ -39,20 +48,49 @@ h2. Link classes
 
 Some classes are pre-defined by convention and have standard meanings attached to names.
 
+h3. provenance
+
 table(table table-bordered table-condensed).
-|_. link_class|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
-|provenance|→Collection  |provided → _collection uuid_
+|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
+|→Collection  |provided → _collection uuid_
 {url→http://example.com/foo.tgz, retrieved_at→1352616640.000}||
-|provenance|Job→Collection     |provided → _collection uuid_||
-|provenance|Specimen→Collection|provided → _collection uuid_||
-|provenance|Human→Specimen     |provided → _specimen uuid_||
-|provenance|Human→Collection   |provided → _collection uuid_||
-|human_trait|Human→Trait  |measured → _trait uuid_ {value→1.83, unit→metre, measured_at→1352616640.000}||
-|identifier|→Human        |hu123456 → _human uuid_||
-|permission|User→Group  |can_manage → _group uuid_|Writable only by a user who can_manage this group|
-|permission|User→Group  |can_read → _group uuid_  |Writable only by a user who can_manage this group.
+|Job→Collection     |provided → _collection uuid_||
+|Specimen→Collection|provided → _collection uuid_||
+|Human→Specimen     |provided → _specimen uuid_||
+|Human→Collection   |provided → _collection uuid_||
+
+h3. permission
+
+table(table table-bordered table-condensed).
+|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
+|User→Group  |can_manage → _group uuid_|Writable only by a user who can_manage this group|
+|User→Group  |can_read → _group uuid_  |Writable only by a user who can_manage this group.
 Gives permission to read any object owned by this group.|
-|resources|User→Collection|wants → _collection uuid_    |Determines whether data can be deleted|
-|resources|User→Job       |wants → _job uuid_    |Determines whether a job can be cancelled|
 
-For links that don't make sense to share between API clients, a link class like @client.my_app_id@ or @client.my_app_id.anythinghere@ should be used.
+h3. resources
+
+table(table table-bordered table-condensed).
+|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
+|User→Collection|wants → _collection uuid_    |Determines whether data can be deleted|
+|User→Job       |wants → _job uuid_    |Determines whether a job can be cancelled|
+
+h3. tag
+
+A **tag** link is a keyword string that identifies a group of collections.  A collection may be assigned multiple tags, and a tag will typically include many collections.
+
+table(table table-bordered table-condensed).
+|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
+|→Collection           | _tag name_ → _collection uuid_||
+
+h3. human_trait
+
+table(table table-bordered table-condensed).
+|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
+|Human→Trait  |measured → _trait uuid_ {value→1.83, unit→metre, measured_at→1352616640.000}||
+
+h3. identifier
+
+table(table table-bordered table-condensed).
+|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
+|→Human        |hu123456 → _human uuid_||
+