Properties

In this document:

Overview

The "properties" section declares a set of resource properties.

../../../../_images/aps-type-properties.png

Each property is a pair of the property name and a {set of attributes}.

  • The property name is a string used for referencing to the property, for example, “admin_name”, “admin_password”, “memory_size”, and so on.

  • A set of attributes describes a value that can be assigned to the resource property, for example:

    • Value type allowed by JSON, such as string, number, boolean, or structure

    • Requirement for encryption

    • Restrictions on the value, such as size and length.

For the list of possible attributes (that is “name”, “type”, “required”, and so on), please refer to the Attributes section.

The following example contains a declaration of three properties (“admin_name”, “admin_password”, and “serial”) and three attributes (type, required, and encrypted):

{
   "id": "http://your.domain.name.org/something/1.0",
   ...
   "properties": {
      /* required string property "admin_name" */
      "admin_name" : {
         "type": "string",
         "required": true
      },
      /* required string property that contains sensitive data "admin_password"*/
      "admin_password": {
         "type": "string",
         "encrypted": true,
         "required": true
      },
      /* optional integer property "serial" */
      "serial": {
         "type": "integer",
         "required": false
      }
   }
}

Such a declaration means that each resource of this type may look as follows:

{
   /* when retrieved through API, each Resource has a meta-section called "aps" */
   "aps": {
      "type": "http://your.domain.name.org/something/1.0",
      ...
   },

   /* each property corresponds to the "properties" declaration */
   "admin_name" : "John Doe",
   "admin_password": "secret",
   "serial": 12345
}

Note

An attribute name is case-sensitive and must match the following pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$. It must be a single word, no spaces allowed.

Warning

The following declaration is not correct because of the whitespace in the property name:

"properties": {
    "admin name": {
      "type": "string",
      "required": true
    },
    ...
}

Attributes

The following attributes are recognized within property declaration.

Note

The only required attribute is type.

Attribute

Value

Default

Example

type

string,
number,
integer,
boolean,
array,
object name
APS type ID

N/A

“type”: “string”
“type”: “array”, “items”: {“type”: “string”}

description

string

null

“description”: “Host name or IP address.”

required

boolean

false

“required”: true

readonly

boolean

false

“readonly”: true

final

boolean

false

“final”: true

encrypted

boolean

false

“encrypted”: true

unit

string

null

“unit”: “gb”

default

match the type

null

“type”: “string”, “default”: “htdocs”
“type”: “integer”, “default”: 1234

format

string from enumerated list

null

“startDate”: { “type”: “string”, “format”: “date-time” }

pattern

regular expression

null

“pattern”: “^[a-zA-Z][0-9a-zA-Z_\-]*”

title

string

null

“title”: “Number of CPUs”

headline

boolean

false

“headline”: true

minLength

integer

null

“minLength”: 2

maxLength

integer

null

“maxLength”: 12

minItems

integer

null

“minItems”: 4

maxItems

integer

null

“maxItems”: 256

uniqueItems

boolean

false

“uniqueItems”: true

enum

array of values defined by type

null

“type”: “string”, “enum”: [“New York”, “Berlin”, “Tokio”]

enumTitles

array of strings describing enum

null

“type”: “string”, “enum”: [“New York”, “Berlin”, “Tokio”],
“enumTitles”: array [“Head Quarter”, “EMEA Office”, “Asian Office”]

access

permission object

{“admin”: true,
“owner”: true,
“referrer”: true,
“public”: false}

“access”: {“referrer”: false}

type

Value: “string”, “number”, “integer”, “boolean”, “array”, structure name (or full URI for an external structure), or APS type ID
Default: N/A
type is either a direct reference to one of APS Primitives, array, or a structure (complex type) defined in the Structures section.

When a property type is “array”, the items attribute must specify the type of the array components. The following example illustrates how to declare a set of URLs:

"properties": {
   ...
   "urls": {
      "type": "array",
      "items": { "type": "string" },
   },
   ...
}

A resource of this type can look as follows:

{
   "aps": {
      "type": "http://my.domain.name.org/infrastructure/web/1.0",
      "id": "ba81a90d-53b7-4985-8e3f-07404435d7e5"
   },
   ...
   "urls": [
      "http://my.domain.name.org/support/",
      "https://my.domain.name.org/control/",
      "http://my.domain.name.org:8080/spec/",
      "http://alias.my.domain.name.org/index.php"
   ],
   ...
}

Note

The type attribute inside items cannot be “array”, meaning that an array cannot embed other arrays.

The limits on the string, integer, and number types are presented in the following table.

PROPERTY TYPE

LIMITS

REFERENCE

string

0 to 4000 characters

String type

integer

Signed integer (64 bit):
-9223372036854775808 to +9223372036854775807

Integer type

number

Double precision (64 bit):
2``(-1023) - smallest exponent
2``(1023) - highest exponent
52 bit (15 decimal digits) precision

Double-precision floating-point format

array of Primitives

Unlimited number of elements

-

array of Structures

Up to 4000 characters total

Such an array is stored as a string with JSON data representation that causes the specified limit

Note

If an APS type needs to have a long array of structures, we recommend defining a separate APS type instead of a structure and then specifying a relationship between the two APS types.

description

Value: string
Default: null
description is a string containing a full description of the resource property.

The following example illustrates how ISV can help server owners to identify the value they need to assign to the hostname property:

"hostname": {
   "type": "string",
   "description": "Server domain name or IP address"
}

required

Value: boolean
Default: false
required indicates whether the resource property must have a value and not be undefined (true value). The default false value of this attribute makes the property value assignment optional.

The following example illustrates how ISV can help server owners not to not miss host name assignment when configuring a new server:

"hostname": {
   "type": "string",
   "required": true
   "description": "Server domain name or IP address"
}

readonly

Value: boolean
Default: false
readonly means that the resource property cannot be set or changed through the user interface of the application. Only the application itself can modify values marked as readonly.

The example below demonstrates a server registration ID property that will be visible but not changeable:

"server_reg_id": {
   "type": "string",
   "readonly": true,
   "description": "Server unique Registration ID assigned automatically"
}

final

Value: boolean
Default: false
final indicates that the resource property can only be assigned a value on resource creation. In other words, the attribute allows a user or an application for the POST and GET operations, but does not allow the use of the PUT operation.

The following example illustrates how to request a mailbox value that will be used as the login name, which cannot be changed after it is assigned:

"mailbox": {
   "type": "string",
   "required": true,
   "final": true,
   "description": "Used as login name"
}

encrypted

Value: boolean
Default: false
encrypted is used to mark sensitive pieces of data that must be encrypted before saving them in database, for example, passwords.

Key points:

  1. The encrypted properties are hidden for reading in UI or in a response to a third party request. For example, no users attempting to get such a property in a UI screen will be able to read it. Encrypted properties are available, however, for applications authenticated through their certificates or OAuth protocol and granted access to the properties. This means:

    • For any other authenticated requester, the APS controller will not return a property marked as encrypted, although that requester can create or change the property when a POST or PUT request was issued respectively.

    • Properties marked as encrypted never appear in logs. They are stored only in the database in the encrypted form.

    • The APS controller must return the value, when a requester is authenticated as an application, assuming the application has the necessary permission for the resource.

  2. The encrypted attribute is not supported for a property presented as an element of an array inside a structure.

  3. The encryption is recommended for properties that must be hidden from users and can be only removed, updated, or recreated by their owner. The system uses high-grade encryption based on AES-CBC with the 128bit key. The encrypted properties cannot be exposed even if the platform database is stolen.

Warning

An application with the legitimate access to a property can read it even if it is encrypted. Even another application can read encrypted property. To prevent this, make sure the access for the property is defined as access:{referrer:false}.

It is the application’s responsibility to handle encrypted properties securely when using them inside the application.

The password property declared in the following example will be encrypted:

"admin_password": {
   "type": "string",
   "encrypted": true,
   "required": true
}

Note

To completely hide a property from any actor except for the application itself, the application developer can explicitly define the access to the resource as follows:

"access": {
   "admin": false,
   "owner": false,
   "referrer": false
}

unit

Value: this must be one of measurement units supported on the hosting platform.
Default: null
unit defines a measurement unit for the property. For example, the core APS resource type defines the Counter, Limit, and Usage structures that can effectively use the unit attribute as in the following example:
"diskusage": {
   "type": "http://aps-standard.org/types/core/resource/1.0#Counter",
   "description": "Diskspace Usage",
   "unit": "gb"
}

The platform supports the following measurement units:

  • “item” - items

  • “unit” - items

  • “kb” - KBytes

  • “mb” - MBytes

  • “gb” - GBytes

  • “item-h” - item-hours

  • “mb-h” - MByte-hours

  • “mhzh” - MHz-hours

The last three units in the above list are used in additive resources to calculate an accumulated amount of a resource over a defined period of time. This is useful for pay-as-you-go charge methods. For example, 1000 mb-h for a disk space may show that 100 MB of disk space was used during 10 hours, or 10 MB was used during 100 hours, and so on, which actually does not make a difference for the billing system using such a unit.

default

Value: this must be one of the primitive types or an array and match the type attribute
Default: null
default indicates one or more default values for the property to be used as a hint for those who uses the resource schema to prepare data for new resource creation.

The following example illustrates how to propose a value to the login property:

"login": {
   "type": "string",
   "default": "admin",
   "required": true
}

format

Value: one of the string values enumerated below
Default: null
format defines the type of data, content type, or microformat to be expected in the resource property values. It may be one of the values listed below, and if so, it must adhere to the semantics describing the format. The attribute must only be used to give meaning to properties of the “string” type.

The following formats are predefined:

  1. date-time: a date in the ISO-8601 format, for example, format YYYY-MM-DDThh:mm:ssZ gives UTC date and time. This is the recommended form of date and time stamp.

  2. date: a date in the format of YYYY-MM-DD.

  3. time: a time in the format of hh:mm:ss.

    Note

    All time-related information must be stored in UTC format on the server and rendered in the user time zone by the UI (user interface).

  4. uri: a URI format. Example:
    “foo://username:password@example.com:8042/over/there/index.dtb?type=animal&name=narwhal#nose”.
  5. email: an email address. Example: “info@aps-standard.org”.

  6. ipv4: an IP version 4 address. Example: “172.16.254.1”.

  7. ipv6: an IP version 6 address. Example: “2001:0db8:0000:0000:0000:ff00:0042:8329”.

  8. ip-address: an IP address, either version 4 or version 6.

  9. domain-name: a valid DNS name, according to RFC-1035. Example: “aps-standard.org”.

  10. host-name: a valid host-name - either a DNS name or IP address RFC-1035.

  11. version: is a string of the following format: “MAJOR_VERSION[.MAJOR_REVISION[.MINOR_VERSION[.MINOR_REVISION]]]”, that is a string composed of up to 4 integers separated by “.”, which together represent a version identifier. For example, “10.23”, “2.0”.

  12. regex: a regular expression compliant with the regular expression specification ECMA-262.

Note

These formatting attributes are not validated by the APS Controller and are only used by UI for input formatting.

The following example illustrates how to require the name server IP address and validate its correct format:

"nameserver": {
   "type": "string",
   "format": "ipv4",
   "required": true,
   "description": "Name Server IP address"
}

pattern

Value: string
Default: null
pattern is a regular expression that a property value must match in order to be valid. When pattern is present, the specifier from the format element is ignored. Regular expressions should follow the regular expression specification from ECMA 262/Perl 5 ECMA-262.

The following example demonstrates how to require login names to begin with an alphabetical character:

"cloudadmin": {
   "type": "string",
   "pattern": "^[a-zA-Z][0-9a-zA-Z_\\-]*",
   "description": "Cloud administrator login name - must start with alphabetical character"
}

title

Value: string
Default: null
title is a string that provides a short description of the instance property.

The following is an extension of the previous example:

"cloudadmin": {
  "type": "string",
  "pattern": "^[a-zA-Z][0-9a-zA-Z_\\-]*",
  "title": "Cloud Admin",
  "description": "Cloud administrator login name - must start with alphabetical character"
}

In a hosting system, it might look as follows:

../../../../_images/properties-title.png

headline

Value: boolean
Default: false
headline - identifies if this property is used to represent a resource in the provider control panel. It marks the properties that will be displayed when creating a resource type of the Application Service Reference class in the auto-generated UI. If no property is marked with it, then all resource properties will be displayed in the control panel.

minLength

Value: integer
Default: null
minLength defines the minimum length of the string value.

maxLength

Value: integer
Default: null
maxLength defines the maximum length of the string value.

In the following example, minimum and maximum limits are set for the password length:

"admin_password": {
    "type": "string",
    "encrypted": true,
    "required": true,
    "minLength": 6,
    "maxLength": 15
}

minItems

Value: integer
Default: null
minItems defines the minimum number of items in an array if the property type is array.

maxItems

Value: integer
Default: null
maxItems defines the maximum number of values in an array if the property type is array.

uniqueItems

Value: boolean
Default: false
uniqueItems indicates that all items in an array instance must be unique, meaning the array does not contain two identical (equal) values.

Two instances are considered equal (not unique) if they are both of the same type and:

  • are null; or

  • are booleans/numbers/strings and have the same value; or

  • are arrays, contain the same number of items, and each item in one array is equal to the corresponding item in another array; or

  • are objects, contain the same property names, and each property in one object is equal to the corresponding property in another object.

The following example demonstrates how the three above-mentioned properties can be used for specifying a list of domain names:

"domains": {
   "type": "array",
   "items": { "type": "strings" },
   "minItems": 1,
   "maxItems": 10,
   "uniqueItems": true,
   "description": "DNS Domains"
}

enum

Value: array of values defined by type
Default: null
enum provides an enumeration of all possible values that are valid for the resource property. If this attribute is defined, the property value must be one of the values in the array in order for the schema to be valid.

Comparison of enum values uses the same algorithm as described for the uniqueItems attribute.

enumTitles

Value: array of strings describing enum
Default: null
enumTitles is an array of strings that provides short description of each possible value of the resource property.

Example with enum and enumTitles:

{
   "id": "http://your.domain.name.org/something/1.0",
   ...
   "properties": {
      ...
      "Regional_Office": {
         "type": "string",
         "enum": ["New York", "Berlin", "Tokio"],
         "enumTitles": ["Headquarters", "EMEA Office", "Asian Office"]
      },
      ...
   },
   ...
}

access

The access attribute can control access to resources, properties and operations for APS roles as described in the Access Attributes section.

When used in a property, the access attribute defines permissions to the property for APS roles.

Value: Permission object
Default: {“admin”: true, “owner”: true, “referrer”: true, “public”: false}
access allows or disallows access to the resource property when a user is either reading or changing the property. When a user attempts to read a prohibited property, the APS controller does not display the property in the output. If a user attempts to submit a value to a prohibited property, an error is returned.

In the following example, a user related with the resource will have access to the site URL:

"properties": {
   ...
   "siteURL": { // property allowed for referrer
      "type": "string",
      "required": true,
      "access": {
        "referrer": true
      }
   }
}

Note

1. A role that has access to an APS resource and a property of the resource can process that property by a CRUD operation only if the operation is allowed for the role by the access attribute of that operation.

2. Refer to the Type Inheritance section for details of what rules are applied to the attributes during type inheritance.