Previous topic

APS Type ID

Next topic

Relations

DOCUMENTATION
Last updated 29-Jul-2016

Properties

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 the {set of attributes}.

  • The property name is a string used for referencing to the property, e.g. “admin_name”, “admin_password”, “memory_size”, etc..
  • The set of attributes completely identifies a value that can be assigned to the resource property, e.g.:
    • Value type allowed by JSON, such as string, number, boolean, or structure
    • Requirement for encryption
    • Restrictions on the value, such as size, length, etc.

For the list of possible attributes (i.e. “name”, “type”, “required”, etc.) please refer to the Attributes section.

The following example contains 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 in the following example:

{
  /* 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_]*$. Pay attention, 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”: false,
“public”: false}
“access”: {“referrer”: true}

Note

Although Specification does not set a limit on the string length, in some implementations there might be additional limitations. For example, in Odin Service Automation, the length of a string in APS properties cannot exceed 2048 symbols.

type

Value: “string”, “number”, “integer”, “boolean”, “array”, structure name (or full URI), 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 such a type might 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.

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 assing 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 illustrated how ISV can help server owners not to miss out 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 attribute 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 demonstrate 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 the POST and GET operations, but does not allow PUT.

The following example illustrates how to request a mailbox value that will be used as the login name and not allowed for changing after its assignment:

"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 in database, e.g. passwords.

Key points:

  1. The encrypted properties are hidden for reading from any requests authenticated through a token. 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 and granted access for the properties. It means:
    • The APS controller will not return a property marked as encrypted when a user or account token was used in the GET request, although it can create or change the property when 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 controller must return the value, when an application certificate is used, assuming the application has needed permission on 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 humans 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 Odin Service Automation 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 it, 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.

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: should 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 list of allowed units depends on the hosting platform. For example, to get the list of units supported in Odin Service Automation, please refer to Odin Service Automation limitation.

default

Value: should be one of primitive types or an array and match the type attribute
Default: null
default indicates a default value (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 ilustrates 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, should adhere to the semantics describing the format. The attribute should 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 ([ISO-8601], [WKPD-8601]) format, e.g., format YYYY-MM-DDThh:mm:ssZ presents UTC date and time. This is the recommended form of date/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 user time zone by 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” - either an ip version 4 or version 6 address.

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

  10. “host-name” - a valid host-name - either DNS name or IP address [RFC-1035].

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

  12. “regex” - A content of the string is a regular expression, following the regular expression specification [ECMA-262].

Note

These formatting attributes are not validated by an APS Controller v2.0, but 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 specificator 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 extention 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 UI (primarily used in auto-generated UI). In the Operation Automation provider control panel, it marks the properties displayed when creating an RT of the ‘Application Service Reference’ class. If no property is marked with it, then all resource properties will be displayed in the UI.

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 values in an array when “array” is the property value.

maxItems

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

uniqueItems

Value: boolean
Default: false
uniqueItems indicates that all items in an array instance must be unique, i.e. 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 vaues 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 following algorithm. Two instances are considered equal 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.

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”: false, “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 not allowed property, the APS controller does not display the property in the output. If a user attempts to submit a value to a not allowed property, an error is returned.

In the following example, a user related with the resource will be able to change the site URL:

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

See also

Please refer to the Type Inheritance section for details of what rules are applied to the attributes during types inheritance.