In this document:
The "properties"
section declares a set of resource properties.
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
},
...
}
The following attributes are recognized within property declaration.
Note
The only required attribute is type.
Attribute |
Value |
Default |
Example |
---|---|---|---|
string,
number,
integer,
boolean,
array,
object name
APS type ID
|
N/A |
“type”: “string”
“type”: “array”, “items”: {“type”: “string”}
|
|
string |
null |
“description”: “Host name or IP address.” |
|
boolean |
false |
“required”: true |
|
boolean |
false |
“readonly”: true |
|
boolean |
false |
“final”: true |
|
boolean |
false |
“encrypted”: true |
|
string |
null |
“unit”: “gb” |
|
match the type |
null |
“type”: “string”, “default”: “htdocs”
“type”: “integer”, “default”: 1234
|
|
string from enumerated list |
null |
“startDate”: { “type”: “string”, “format”: “date-time” } |
|
regular expression |
null |
“pattern”: “^[a-zA-Z][0-9a-zA-Z_\-]*” |
|
string |
null |
“title”: “Number of CPUs” |
|
boolean |
false |
“headline”: true |
|
integer |
null |
“minLength”: 2 |
|
integer |
null |
“maxLength”: 12 |
|
integer |
null |
“minItems”: 4 |
|
integer |
null |
“maxItems”: 256 |
|
boolean |
false |
“uniqueItems”: true |
|
array of values defined by type |
null |
“type”: “string”, “enum”: [“New York”, “Berlin”, “Tokio”] |
|
array of strings describing enum |
null |
“type”: “string”, “enum”: [“New York”, “Berlin”, “Tokio”],
“enumTitles”: array [“Head Quarter”, “EMEA Office”, “Asian Office”]
|
|
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 IDDefault: N/Atype
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”, theitems
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 insideitems
cannot be “array”, meaning that an array cannot embed other arrays.The limits on the
string
,integer
, andnumber
types are presented in the following table.
PROPERTY TYPE
LIMITS
REFERENCE
string
0 to 4000 characters
integer
Signed integer (64 bit):-9223372036854775808 to +9223372036854775807
number
Double precision (64 bit):2``(-1023) - smallest exponent2``(1023) - highest exponent52 bit (15 decimal digits) precision
array
of PrimitivesUnlimited number of elements
-
array
of StructuresUp 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: stringDefault: nulldescription
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: booleanDefault: falserequired
indicates whether the resource property must have a value and not be undefined (true
value). The defaultfalse
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: booleanDefault: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: booleanDefault: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: booleanDefault: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 asaccess:{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 theunit
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 attributeDefault: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 belowDefault: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”.
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: stringDefault:null
pattern
is a regular expression that a property value must match in order to be valid. Whenpattern
is present, the specifier from theformat
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: stringDefault: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: booleanDefault: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: integerDefault:null
minLength
defines the minimum length of the string value.
maxLength
¶Value: integerDefault: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: integerDefault:null
minItems
defines the minimum number of items in an array if the property type isarray
.
maxItems
¶Value: integerDefault:null
maxItems
defines the maximum number of values in an array if the property type isarray
.
uniqueItems
¶Value: booleanDefault: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 typeDefault: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 enumDefault: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 objectDefault: {“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.