Search

Skip to end of metadata
Go to start of metadata

Several of the API objects (namely accounts and organisations) contain ‘attributes’ fields. These fields are designed to contain an extendable list of attributes relating to the object.

In order for an API client to obtain a list of the acceptable values for these attributes (for instance to render an input form in a UI), it is possible to query the API for a ‘schema’ object. This object defines acceptable attributes for a given object and additional metadata such as whether such attributes are required (when creating new accounts or organisations).

It is possible to add additional attributes to the schema for your domain. To do this, go to the administration dashboard (https://admin.openthens.net). You need to login as the main administrator for your domain (not a sub-organisation) and go to Preferences > Schema editor. See: Schema editor

Reading an attribute schema

Prerequisites

To query an attribute schema, a client application must

  • authenticate to the API as described in Authenticating to the API.
  • obtain a link to the desired schema object from the entry point resource.

Procedure

Schemas for ‘organisation’ objects may be queried by performing a GET to:

https://admin.openathens.net/api/v1/example.org/schema/organisation

Schemas for ‘account’ objects may be queried by performing a GET to:

https://admin.openathens.net/api/v1/example.org/schema/account/<type>

Where type should be replaced with one of ‘personal’, ‘administrator’ or ‘access’, depending on the desired account type for which the schema applies.

This returns an application/vnd.eduserv.iam.admin.attributeSchema-v1+json object. This contains a list of ‘attribute definitions’.

Example

Request:
GET /api/v1/example.org/schema/account/personal HTTP/1.1
Authorization: OAApiKey <api-key>
Response (success):
HTTP/1.1 200 OK
Content-Type: application/vnd.eduserv.iam.admin.attributeSchema-v1+json
 
{
  "id" : "7",
  "definitions" : [ {
    "name" : "username",
    "type" : "string",
    "displayName" : "Username",
    "multiValued" : false,
    "required" : false,
    "options" : { },
    "order" : 1,
    "editable" : false
  }, {
    "name" : "title",
    "type" : "string",
    "displayName" : "Title",
    "multiValued" : false,
    "required" : false,
    "options" : { },
    "order" : 2,
    "editable" : true
  }, {
... detail omitted
  } ],
  "links" : [ {
    "href" : "/api/v1/example.org/schema/account/personal",
    "rel" : "self",
    "type" : "application/vnd.eduserv.iam.admin.attributeSchema-v1+json",
    "method" : "get"
  } ]
}

application/vnd.eduserv.iam.admin.attributeSchema-v1+json object

Object field

Description

name

The name of the attribute. This is the name that should be used to refer to the attribute when performing operations on API objects containing attributes. For instance this forms the key on values in the ‘attribute’ field on account and organisation objects, and their associated error objects.

displayName

A human-readable name for the attribute. This may be used to label fields on a UI form.

description

A short description for the attribute. This may be used to provide additional information on a UI (e.g. help text).

type

The base type of data held in the attribute.

validateAs

Additional validation that the API will apply to data in addition to the base type.

multiValued

A Boolean value that defines whether the attribute may hold multiple values.

required

A Boolean value that defines whether the attribute is mandatory.

options

Additional options that the API will apply when processing the attribute. Options depend on the attribute type.

order

The relative order of the attribute in the list of attributes in the complete schema. This may be used to affect the order of fields on a UI input form.

editable

Whether the attribute is editable via the API. Non-editable attributes may be defined as read-only, or may contain values that are automatically generated by the API and as such cannot be edited directly.

Standard attributes

Within the OpenAthens system, attributes are definable per domain. All domains will have a standard set of attributes though, listed below. Attributes are not exclusively limited to those appearing in this list – querying the schema for a particular domain may therefore return attributes not shown below. All attributes listed below are optional, unless otherwise stated.

Attribute

NotesDescription

username

read-only, unique

The account login name.

title

 

The title for the user (e.g. Mr, Mrs etc.)

forenames

 

The user’s first name (required).

surname

 

The user’s last name (required).

institution

 

The name of the organisation to which the user belongs (required).

department

 

The name of the department to which the user belongs.

position

 

The position (e.g. Job title) of the user.

emailAddress

 

The email address for the user (required).

uniqueEmailAddress

unique

A unique email address for the user. This is only required if the user can login with their email address, in which case both this and the emailAddress attribute will be set.

phone

 

The phone number for the user.

fax

 

The fax number for the user.

identifier

 

An additional identifier for the user (e.g. staff number).

postalAddress

 

The postal address for the user.

notes

 

Additional notes for the account.

persistentUID

read-only, unique

An automatically-generated persistent identifier for the account.

organisationNum

read-only, unique

The nearest parent organisation to the user in the organisation hierarchy.

 

See also:

 

  • No labels