General Definitions

In this document you will find the general overview of the APS type structure and the description of the section containing general properties.

Type Definition Structure

APS schema consists of the following sections:

  • General Section: the general declaration of the APS type.

  • Properties: the definition of the resource properties.

  • Relationship: the description of the semantic relationship with resources of other APS types.

  • Operations: a 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).

../../../../_images/aps-type-resources.png

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 this APS type

id

Yes

The fully-qualified APS Type ID

name

Yes

The “friendly” name of the type

implements

Yes

The list of the APS types that are implemented (inherited) by this APS type (interface inheritance)

access

No

Permissions to resources for APS roles

apsVersion

The apsVersion element declares the minimal APS API version that 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. For example:

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_]*$. 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 the http://aps-standard.org/types/core/application/1.0 type.

See also the 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 or changing the resource, or calling an operation of the resource. The access is granted for the roles that can be assigned to actors and for the public attribute with the following default definition:

"access": {
   "admin": true,
   "owner": true,
   "referrer": true,
   "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 }
   ...
}