About Labels Policies

What is a labels policy?

Label policies are used to define which labels can be used, and how, by records in ledger. They have schema labels which defines a specific structure of policy rules contained in values of the policy.

POST /v2/policies
 
{
  ...,
  data: {
    handle: '...',
    schema: 'labels',
    record: '<record>',
    filter: { ... },
    values: [ ... ]
  }
}

There are root properties in policy record and filter which refer to the record type and the record value and are used to evaluate whether the policy will be applied to record when a proof to change record labels is submitted.

The principle open unless whitelisted which ledger follows in all kinds of rules is valid here also. So if for a record whose labels are to be changed there isn’t any matching labels policy (by record and filter) then the operation of changing labels will be by default accepted. Otherwise the operation needs to be explicitly granted by one of applicable policy rules.

Property filter represents standard ledger filtering concept where language used in filter expression is mongo-compatible.

Defining allowed labels

To define which labels can be used, we’ll use labels field in the policy values. It is an array of strings and has a meaning that the rule grants to users the ability of attaching any of these labels to a record.

POST /v2/policies
 
{
  ...,
  data: {
    handle: 'preferred-account-anchor',
    schema: 'labels',
    record: 'anchor', // It applies only to anchors
    'filter: {
      schema: 'account'  // It applies only to anchors with a schema "account"
    },
    values: [
      {
        labels: ['preferred']
      }
    ],
    custom: {
      description: 'Marks a account anchor as preferred in the system'
    }
  }
}

Constraining Uniqueness

Sometimes we want to limit a label so that it can’t repeat, e.g. only one account anchor of a wallet can be labeled as preferred. It can be done by adding a set of unique record properties to a label policy rule:

POST /v2/policies
 
{
  ...,
  data: {
    handle: 'preferred-account-anchor-per-wallet',
    schema: 'labels',
    record: 'anchor',
    filter: {
      schema: 'account'
    },
    values: [
      {
        labels: ['preferred'], 
        unique: ['wallet']
      }
    ],
    custom: {
      description: 'Marks a preferred account anchor per wallet'
    }
  }
}

This example can be expanded to other use cases by listing more properties as unique. For example, if you want to control the preferred anchor per wallet and symbol, you want to declare it like this:

POST /v2/policies
 
{
  ...,
  data: {
    handle: 'preferred-account-anchor-per-wallet-symbol',
    schema: 'labels',
    record: 'anchor',
    filter: {
      schema: 'account'
    },
    values: [
      {
        labels: ['preferred'], 
        unique: ['wallet', 'symbol']
      }
    ],
    custom: {
      description: 'Marks a preferred account anchor per wallet and symbol'
    }
  }
}