Weekly design meeting #26

This week we discussed how to put <selection> in use. It that has been in the schema since early 2018 but hasn't seen practical use.

Basic design of <selection>

An example of <selection> in EntryToken.xml

<ts:selection id="expired" filter="expired=TRUE">
    <ts:plurals xml:lang="en">
      <ts:string quantity="one">A expired Ticket</ts:string>
      <ts:string quantity="other">Expired Tickets</ts:string>
    <ts:string xml:lang="zh">已经过期的票</ts:string>

When there are a lot of EntryTokens, a user agent might display a tag "Expired Tickets" which the user can use to only show tokens in that selection.

A selection can be referred to it in the exclude of an action:

<action exclude="expired">

It means that action "Enter" is not available to the user if

  • the user's token belongs to the expired selection.
  • the user is in multi-token selection mode, and some of the tokens selected is in a selection that the action excludes.

Address the discoverability of actions with <denial>

A user might be frustrated that the Enter action is not available with their EntryToken, especially if it was there a few days ago (thanks to a recently expiry). Better user experience is:

  • to render Entre action button nonetheless, and if the user clicks that button,
  • give the user a denial message (or render a disabled button together with a denial message), so that the user knows
  • that his EntryToken can't be used to Enter because it has expired.

Similarly, if the token wishes to encourage the user to discover its features, it might include an action like "Redeem a free flight" with a denial message of "until you have 300,000 points".

For this to work, one can add a denial message such as:

<ts:selection id="expired" filter="expired=TRUE">
    <ts:plurals xml:lang="en">
      <ts:string quantity="one">Expired Ticket</ts:string>
      <ts:string quantity="other">Expired Tickets</ts:string>
    <ts:string xml:lang="zh">已经过期的票</ts:string>
    <ts:plurals xml:lang="en">
      <ts:string quantity="one">The ticket has expired</string>
      <ts:string quantity="other">The tickets have expired</string>

If an action's exclude refers to a selection that has a denial message, that action is never hidden from the token. Instead, the denial message is provided when the user tries to access it.

Previllaged actions

Let's say that you are elected as a board member of a DAO, a title that comes with the privilege to start a proposal. You might have an action "Propose". It would start like this:

<action exclude="ordinary-membership">

This is rather awkward to read. If there are 3 levels (provisional membership, ordinary membership and board membership) you might resort to this

<action exclude="ordinary-membership provisional-membership">

Or this

<action exclude="non-board-membership">

None of them is as elegant as a new available-to attribute:

<action available-to="board-membership">

We decide to not to include available-to despite its apparent usefulness, as it may be better addressed with <role> which are to be designed as a context later this year, and that we should get by with exclude until <role> is designed and implemented. Conceptually, such previllage is the property of the account (the address is a previlleged address) instead of the property of the token. For example, if a previllaged user is able to sell his kitties back to the issuer at discount, it doesn't matter which kitty he sells, as long as the kitty is under his previllaged account.



<selection> might be a bad choice of word because:

  • It makes a TS author feel that they can apply this to all kinds of data objects, including Blockchain (Ethereum) smart contract events. While the TokenScript team has no inclination to support such use. Calling it <token-set> would end this ambiguity.

  • When the user makes multi-selection (on mobile, typically by hold-and-click), the word selection is ambiguious, as it might refer to user's selection. Again, calling it <token-set> would end this ambiguity.

However, <selection> is intended to be used for attestations, like this:

<selection id="proof-of-age" filter="birthDate=*">

Calling it <token-set> might confuse some authors who don't think attestations as tokens.


James Brown didn't like the word denial, but didn't find a better word.


It's proposed to use include instead of availble-to, e.g.

<action id="propose" include="board-membership">

My (Weiwu)'s reason against it is that it's hard to say which one prioritise over another between exclude and include:

<action id="propose" exclude="propose-quota-met" include="board-membership">

However it's easy to tell if we use available-to

<action id="propose" exclude="propose-quota-met" available-to="board-membership">

Where exclude clearly precedes available-to regardless the order they appear.

P.S. We also decided to drop <attribute-types> as a container of attributes.

@weiwu.zhang Should one of the ids be renamed so they don't clash?

    <ts:selection id="expired">
      <ts:exclude selection="expired"/>
    <ts:attribute-type id="expired" syntax=""> <!-- boolean -->

@weiwu.zhang Did we intend to address namespacing aka. id/name/ref in this session too so we can include them in the current schema upgrade?

Yes in the 06 schema all ids are ids, all names are names and whenever possible, refs are by the kind of reference (e.g. module="…" means a reference to a <module name="…">