General Definitions

Structure of Type Definition

APS schema consists of the following sections:

• General Section - general declaration of the type.
• Properties - definition of resource parameters.
• Relationship - description of semantic relationship with resources of other types.
• Operations - list of non-CRUD operations supported by resources of this type.
• Structures - reusable data structure definitions (to be used in the Properties or Operations sections).

General Section

An APS type definition contains the general section followed by the other four sections as presented in the following example:

{
   "apsVersion": "2.0",

   "name": "Mailbox",

   "id": "http://your.domain.name.org/types/mail/mailbox/1.0",
   "implements": [
      "http://aps-standard.org/types/core/resource/1.0",
      "http://aps-standard.org/types/mail/archiving/1.0"
   ],

   "properties"  : { "..." },
   "operations": { "..." },
   "relations": { "..." },
   "structures": { "..." }
}

The general section contains the following attributes:

Attribute	Required?	Overview
apsVersion	Yes	The minimal version of the APS API required by the type
id	Yes	Fully-qualified APS Type ID
name	Yes	“Friendly” name of the type
implements	Yes	List of the APS types that are implemented (inherited) by this APS type (interface inheritance)
access	-	Permissions to resources for APS roles

apsVersion

The apsVersion element declares the minimal APS API version the APS type was written for. This field is mandatory in any APS type definition.

id

The id element defines a fully-qualified unique APS type ID in the http://basename/major[.minor] format. Examples:

http://www.aps-standard.com/infrastructure/pcs/1.1
http://www.odin.com/poa/mailbox/2.0

Please refer to APS Type ID for more details.

name

The name element is required for code generation and documentation purposes. It will also be used to give a name to the top-level structure representing a resource instance. Basically, this is a “friendly” name that is not visible anywhere outside of the type definition file and cannot be used to refer to the type in other type definitions.

Note

As with all other names, the following naming pattern should be matched: ^[a-zA-Z_][a-zA-Z0-9_]*$. Pay attention that it must be a single word, no spaces allowed.

implements

The implements array contains a list of APS Type ID. Each APS type that can be instantiated by an APS controller must implement at least the http://www.aps-standard.org/core/resource/1.0 or http://aps-standard.org/types/core/application/1.0 type.

See also

Type Inheritance section for more details.

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 the general section of the type definition, the access attribute defines permissions to all resources instantiated from the type.

access allows or disallows an actor to access a resource when that actor is either reading the resource, changing the resource, or calling an operation of the resource. By default, the access is defined as:

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

In the following example, a user related with a resource will be able to operate the resource as a whole object:

{
   "apsVersion": "2.0",
   "name": "Mailbox",
   "id": "http://your.domain.name.org/types/mail/mailbox/1.0",
   "implements": [
      "http://aps-standard.org/types/core/resource/1.0",
      "http://aps-standard.org/types/mail/archiving/1.0"
   ],
   "access": { "referrer": true }
   ...
}

← JSON Schema

APS Type ID →