Attribute’s properties¶

We can distinguish the following features of attributes used in object specification:

`Attribute's properties`¶
Property	Possible values	Default value	Description
type	`boolean` `number` `string` `number-array` `string-array`	`string`	Attribute’s type in JSON requests.
readonly	`true` `false`	`false`	When set to `true`, it cannot be set during POST or modified during PATCH.
immutable	`true` `false`	`false`	When set to `true`, it can be set only during POST, but cannot be modified during PATCH.
ignore-case	`true` `false`	`false`	When set to `true`, `apid` will ignore letters case when filtering by this attribute.
allow-empty	`true` `false`	`false`	When set to `true`, this string attribute can be set to an empty string.
default	`<value>`	No default	Attribute’s default value.
protected	`true` `false`	`false`	The attribute’s value is a secret and shouldn’t be returned to the caller.
grant	`<objtype>`	No default	Require grant on `<objtype>` and use this attribute as an ID for the `<objtype>` object.
required	`true` `false`	`false`	When set to `true`, the attribute is always required.
required-by	`{ <attribute>: <value>, ... }`	No default	List of attributes and their values that require this attribute. If the value is an empty object then this attribute is required whenever the given attribute exists. Multiple `''required-by''` properties can be specified.
requires	`{ <attribute>: <value>, ... }`	No default	List of attributes and their values required by this attribute. If the value is an empty object then the given attribute is required, but value doesn’t matter. Multiple `''requires''` properties can be specified. If that is the case then at least one of them has to be met.
values	`<value>` or: `[ <value>, ... ]`	No default	Value or an array of possible values for this attribute.
value-labels	`[ <label>, ... ]`	No default	User-friendly names for all the values, used in graphical user interfaces.
value-range	`[ <minval>, <maxval> ]`	No default	Value range for a numeric attribute.
value-regexp	`<regular expression>`	No default	Regular expression that the value has to match.
unique	`true` `false` or: `<attribute>` or: `[ <attribute>, ... ]`	`false`	The given attribute is unique by itself (when `true`) or is unique when combined with other attributes.
expensive	`true` `false`	`false`	The given attribute is expensive to retrieve because it requires an additional operations in the database or a subquery.
description	`string`	No default	Short description of the attribute.

Selected use examples¶

Required-by

Description:

In the following example, the attribute is required when protocol is set to either ssh or rdp.

Example:

"required-by": { "protocol": [ "ssh", "rdp" ] }

Description:

Example below shows that when "external_port" is defined, this attribute is required.

Example:

"required-by": { "external_port": { } }

Description:

Multiple "required-by" properties can be specified. Two equivalent examples below shows that this attribute is required either:

when protocol is "ssh" or

when protocol is http or rdp and tls_enabled is true.

Example:

"required-by": { "protocol": "ssh" },
"required-by": { "protocol": [ "http", "rdp" ], "tls_enabled": true }

Equivalent example:

"required-by": { "protocol": "ssh" },
"required-by": { "protocol": "http", "tls_enabled": true },
"required-by": { "protocol": "rdp", "tls_enabled": true }

Requires

Description:

Following example shows that this attribute requires protocol to be set to ssh or rdp.

Example:

"requires": { "protocol": [ "ssh", "rdp" ] }

Description:

Following example shows that "external_port" is required to exist, but its value is not important.

Example:

"requires": { "external_port": { } }

Description:

Following example shows that this attribute requires protocol to be set to rdp and "tls_enabled" to be set to true.

Example:

"requires": { "protocol": "rdp", "tls_enabled": true }

Unique

Description:

Example of unique attribute with no dependencies.

Example:

"id": {"unique": true}

Description:

Example of unique attribute with single dependency - a pair of those attributes is unique.

Example:

"safe_id": {
        "unique": "user_id"
},
"user_id": {
        "unique": "safe_id"
}

Description:

Example of unique attribute with double dependency - three attributes together are unique.

Example:

"account_id": {
        "unique": [ "listener_id", "safe_id" ]
},
"listener_id": {
        "unique": [ "account_id", "safe_id" ]
},
"safe_id": {
        "unique": [ "account_id", "listener_id" ]
}