Fetching attribute schemas via the API

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"
  } ]
}

CODE

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