Properties¶

In this document:

Overview
Attributes

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”} “type”: “http://aps-demo.org/samples/basic/vps/1.0”
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

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:

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.

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

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:

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.

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

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

uri: a URI format. Example:

“foo://username:password@example.com:8042/over/there/index.dtb?type=animal&name=narwhal#nose”.

email: an email address. Example: “info@aps-standard.org”.

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

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

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

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

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

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

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:

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

← APS Type ID

Relationship →

CloudBlue Commerce API (DRAFT)

Table Of Contents

Previous topic

Next topic

Properties¶

Overview ¶

Attributes ¶

`type`¶

`description`¶

`required`¶

`readonly`¶

`final`¶

`encrypted`¶

`unit`¶

`default`¶

`format`¶

`pattern`¶

`title`¶

`headline`¶

`minLength`¶

`maxLength`¶

`minItems`¶

`maxItems`¶

`uniqueItems`¶

`enum`¶

`enumTitles`¶

`access`¶

CloudBlue Commerce API (DRAFT)

Table Of Contents

Previous topic

Next topic

Properties¶

Overview¶

Attributes¶

type¶

description¶

required¶

readonly¶

final¶

encrypted¶

unit¶

default¶

format¶

pattern¶

title¶

headline¶

minLength¶

maxLength¶

minItems¶

maxItems¶

uniqueItems¶

enum¶

enumTitles¶

access¶

Overview ¶

Attributes ¶

`type`¶

`description`¶

`required`¶

`readonly`¶

`final`¶

`encrypted`¶

`unit`¶

`default`¶

`format`¶

`pattern`¶

`title`¶

`headline`¶

`minLength`¶

`maxLength`¶

`minItems`¶

`maxItems`¶

`uniqueItems`¶

`enum`¶

`enumTitles`¶

`access`¶