Previous topic

APS Type ID

Next topic

Relationship

Odin Automation SDK (DRAFT)
Last updated 15-Dec-2017

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, length, and other.

For the list of possible attributes (that is “name”, “type”, “required”, and so on), 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}

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

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

In a case an APS type needs to have a long array of structures, the recommended way is to define a separate APS type instead of a structure and then specify 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 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 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 using the PUT operation.

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, for example, 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 to 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 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 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 for a 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 difference for the billing system using such a unit.

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 format, for example, 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 the 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]]]”, that is a string composed of up to 4 integers separated by “.”, which together represent a version identifier. Examples: “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 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 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, that is 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 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”: 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
      }
   }
}

Note

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