From 2d8c5fb2e83f43b3eded31c0c957e534873ec982 Mon Sep 17 00:00:00 2001
From: Nadja Reitzenstein <me@dequbed.space>
Date: Tue, 1 Nov 2022 12:44:33 +0100
Subject: [PATCH] Add resource description fields

---
 claim.capnp    |  4 ++--
 resource.capnp | 42 +++++++++++++++++++++++++++++++-----------
 2 files changed, 33 insertions(+), 13 deletions(-)

diff --git a/claim.capnp b/claim.capnp
index 6b96521..cab5fac 100644
--- a/claim.capnp
+++ b/claim.capnp
@@ -22,7 +22,7 @@ interface Lockable {
     restore @0 ( sturdy :SturdyRef ) -> ( lock :Lock );
     # Restore a previously saved SturdyRef pointing to a Claim
 
-    lock @2 () -> ( lock :Lock );
+    lock @1 () -> ( lock :Lock );
     # Take exclusive access to a resource, disowning all other claims on this resource.
     #
     # On resources that do not allow concurrent claims to exist this method behaves similar to
@@ -56,5 +56,5 @@ interface Lock extends (Claim) {
 
     downgrade @0 () -> ( claim :Claim );
     # Downgrade a lock to a claim, allowing additional claims to be granted on resources that allow
-    # for concurrent access.
+    # for concurrent access.  Calling this capability will invalidate the Lock capability.
 }
diff --git a/resource.capnp b/resource.capnp
index 4bc5f82..6285712 100644
--- a/resource.capnp
+++ b/resource.capnp
@@ -7,34 +7,54 @@ using import "persistent.capnp".Persistent;
 using import "notify.capnp".Notifyable;
 using import "interest.capnp".Interestable;
 using import "claim.capnp".Claimable;
+using import "claim.capnp".Lockable;
 
 using import "utils.capnp".OID;
+using import "utils.capnp".L10NString;
 
 interface Resource extends (Persistent) {
     # BFFH's smallest unit of a physical or abstract "thing".  A resource can be as simple and
     # physical as a table, as complex as a PCB production line or as abstract as "people with
     # specific know-how are present".
 
-    type @0 () -> ( types :List(OID) );
-    # The 'type' of Resource. Each OID in the list specifies certain behaviours that this Resource
-    # follows.
-
-    describe @1 () -> Description;
-    # Return information about this resource. This information is usually rather static, but may
+    describe @0 () -> Description;
+    # Return information about this resource.  This information is usually rather static, but may
     # change between calls.
 
-    caps @2 () -> ( notify :Notifyable, interest :Interestable, claim :Claimable, lock :Lockable );
+    caps @1 () -> ( notify :Notifyable, interest :Interestable, claim :Claimable, lock :Lockable );
     # return the capabilities an user has for this resource.
     # `notify`: NULL if the user does not have permission to read this resource, or if this resource
-    # is not notifiable
+    #           is not notifiable
     # `interest`: NULL if this resource is not interestable or the user does not have permission to
-    # set interests for this resource.
+    #             set interests for this resource.
     # `claim`: NULL if the user does not have permission to write to this resource, or if this
-    # resource type does not support claiming.
+    #          resource type does not support claiming.
     # `lock`: NULL if the user does not have permission to manage this resource, or if this resource
-    # type does not support claiming or locking.
+    #         type does not support claiming or locking.
 }
 
 struct Description {
+    types @0 :List(OID);
+    # The 'type' of Resource.  Each OID in the list specifies certain behaviours that this Resource
+    # follows.
 
+    urn @1 :Text;
+    # The URN of this resource.
+
+    category @2 :Text;
+    # A category this resource belongs to.  If a resource was not assigned a category this is NULL.
+
+    name @3 :L10NString;
+    # A human-facing name for this resource.  A name should be short and recognizable, and is meant
+    # as the primary identifier for users to find a resource.
+
+    description @4 :L10NString;
+    # A human-facing description for this resource.  Descriptions are longer-form text that give
+    # additional information about a resource beyond a name.  They are meant to provide either
+    # further identifying information or important information that users should be actively shown
+    # when selecting this resource.
+
+    wiki @5 :Text;
+    # An URI to further detailed information about this resource, e.g. in a wiki.  This SHOULD be an
+    # http or https URL.
 }