api.fabaccess-api/resource.capnp

@0x8c2f829df1930cd5;

using CSharp = import "programming_language/csharp.capnp";
$CSharp.namespace("FabAccessAPI.Schema");

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".

    describe @0 () -> Description;
    # Return information about this resource.  This information is usually rather static, but may
    # change between calls.

    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
    # `interest`: NULL if this resource is not interestable or the user does not have permission to
    #             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.
    # `lock`: NULL if the user does not have permission to manage this resource, or if this resource
    #         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.
}