attribute-dictionary.adoc

TAP Attribute Dictionary

v1.0.0 April 2021

Copyright © 2021 University Corporation for Advanced Internet Development, Inc.

About the TAP Attribute Dictionary

The TAP Attribute Dictionary defines a set of common attributes used across various components of the TAP portfolio. The authoritative Attribute Dictionary is abstract — it is not bound to any particular representation. However, to be useful the Attribute Dictionary must then be mapped to a specific form, such as JSON. Such a mapping is called a Representation.

A Representation of the Attribute Dictionary is typically bound to a Protocol, which defines the context in which the Representation is used. For example, the ID Match Protocol uses the JSON Representation of the Attribute Dictionary.

About Attribute Dictionary Attributes

There are no required attributes from the perspective of the Attribute Dictionary. It is up to a given Protocol using the Attribute Dictionary to determine which attributes are required, and how such status is conveyed between participants if not specified as part of the Protocol itself.

Attributes may be simple or complex. Complex attributes have sub-attributes. It is up to a given Representation to determine the representation of complex attributes.

Note that all attributes, whether simple or complex, may have metadata attached if supported by the relevant Protocol. It is up to the Representation to describe how metadata attaches to attributes.

Where attributes are multi-valued, it is up to a given Protocol to determine whether multiple values are supported, and how such status is conveyed between participants. It is up to a Representation to determine the representation of multiple values.

Multi-valued attributes may be represented by the use of plural versions of the attribute names (eg: people vs person). For consistency, the plural name is provided as part of each attribute definition. It is up to a Representation to determine if plural names are in use.

Attribute names use camelCase with an initial lowercase letter. Representations may instead require the use of underscore notation, in which case an underscore is inserted before each capital letter, and the capital letter is then lower cased.

Attribute names are case insensitive, but should be case preserving.

Tip

The names of all attributes in the Attribute Dictionary are intended to provide a standard reference for wire or protocol level representations. While the names used here may be a helpful starting point, user interfaces should carefully consider terminology rendered for end users, and select context appropriate names and representations (including representation in languages other than English).

Attribute Data Types

Attribute Dictionary attributes are typed, as follows:

• binary: Representation specific encoding of binary data.

• boolean: Representation specific encoding of true or false.

• country: ISO 3166-1 two letter country code.

• date: Date in ISO 8601 (YYYY-MM-DD) format.

• dateTerm: A datestamp used to indicate intervals such as a semester, trimester, or quarter. The format is YYYY-L#, where L is one of H (half year), T (third), or Q (quarter), and # is the sequential number. eg: 2015-H2 designates the second semester of the 2015 academic year (and so might physically be in the year 2016).

• dateTime: A timestamp in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).

• extensibleEnumeration: The enumerated values of the Attribute Dictionary vocabulary should be supported when specified values are relevant, however Protocols and implementations may add to the vocabulary. It is up to the Protocol to determine how such additions are conveyed between participants.

• integer: An integer, which may be further constrained by an attribute definition.

• locale: A locale in LL_CC format, which is an ISO 639-1 language code, an underscore, and an ISO 3166-1 two letter country code.

• region: ISO 3166-2 subdivision code, not including country prefix (eg: BC not CA-BC).

• string: Strings are case preserving but not case sensitive, unless otherwise specified for a given attribute. Strings support UTF-8 unless otherwise specified for a given attribute or Representation.

Supplemental Local ("Ad Hoc") Attributes

Additional attributes may be locally defined in order to supplement the Attribute Dictionary attributes defined in this document. These attributes are referred to as Ad Hoc attributes.

Ad Hoc attributes are identified by use of namespaces. The specific format for indicating the namespace is up to each Representation, but the intention is for the namespace to be represented for each attribute. An appropriate unique identifier should be selected for the namespace label. For example, a University might use its top level domain (university.edu) while an application might use an OID within a space controlled by the application developer.

Note

The Attribute Dictionary does not impose a specific namespacing requirement for local values added to an extensibleEnumeration. Local deployments will need to balance the likelihood that these values could eventually be added to the Attribute Dictionary definition (in which case, for forward compatibility, namespacing should not be used) against the likelihood that these values are highly tailored to the local deployment (in which case namespacing should be used to avoid conflict with potential revisions to the Attribute Dictionary).

Attribute and Record Metadata

The following Metadata attributes are available to describe a record or an attribute within a record:

• actor: A string representing an identifier associated with the person or system process that performed the most recent modification to the record

• created: A dateTime describing when the attribute value was created.

• deleted: A boolean value that, when true, indicates the attribute has been deleted.

• id: A case sensitive string used to uniquely identify the attribute value. No specific format is required, ids could be integers, UUIDs, or any other type encodable as a string.

• lastModified: A dateTime describing when the attribute value was last modified.

• release: An extensibleEnumeration describing the release policy for the attribute value. When an attribute does not have an explicit release policy, the next nearest parent release policy (a parent attribute or the record level policy) applies. Defined values are

  • public: The attribute and value may be used without restriction.

  • internal: The attribute and value are to be used for official organizational purposes only, and may not be redistributed without permission.

  • private: The attribute and value may not be used for any purpose without permission.

• revision: A positive integer describing the revision number for the value of the attribute. For example, if the value for the attribute was initially created as blue, but was subsequently changed to green, the revision value for green is 2.

• source: A string representing the authority or source of the associated record or attribute.

Response Metadata

The following Metadata attributes are available to describe a response:

• objectType: An extensibleEnumeration describing the type of record(s) being returned. Defined values are

  • department

  • group

  • organization

  • person

• version: A string describing the API (Protocol) version this response corresponds to.

Pagination

The following attributes are defined for use when paginating results within a Protocol:

Pagination Request Attributes

• direction: A string controlling the direction of the sort of the requested objects. Defined values are

  • asc: Ascending

  • desc: Descending

• limit: A positive integer indicating the maximum number of results to return per page. It is acceptable for the response to include fewer than limit records.

• page: A positive integer indicating the number of the page to return results for. As a positive integer, the first page of results is 1.

• sort: The attribute to sort the results on.

Pagination Response Metadata

Pagination Response Metadata is typically included with Response Metadata, but the specifics are left to the Representation.

• currentPage: A positive integer indicating the current page of results. This will typically correspond to the page request attribute if specified.

• itemsPerPage: A non-negative integer indicating the number of records in the current page of results. This will typically correspond to the limit request attribute if specified, though it may be less.

• pageCount: A non-negative integer indicating the total number of pages.

• startIndex: A positive integer indicating the index of the first result (out of totalResults) in the current page, starting from 1 (the first result on the first page).

• totalResults: A non-negative integer indicating the total number of records.

Attribute Dictionary Attributes

address

A physical or postal address.

Plural	addresses
Type	complex
Subattributes	country, formatted, language, locality, postalCode, region, room, streetAddress, type, verified

address: country

Country in which the address is located.

Type

country

address: formatted

Address rendered as a single string, possibly with embedded newlines (\n).

Type

string

address: language

The language encoding of the address.

Type

locale

address: locality

Locality information from an address, such as a city name.

Type

string

address: postalCode

Postal code from an address.

Type

string

address: region

Region information from an address, such as a state or province.

Type

region

address: room

Room from an address.

Type

string

address: streetAddress

Street or site information from an address, including street name, house number, etc. May include embedded newlines (\n).

Type

string

address: type

Address type. Defined values are

• break: An address for use during organizational breaks (eg: summer)

• campus: An address located on an organization’s campus

• home: The home address of the subject

• office: The office address of the subject

• parent: For students, an address belonging to a parent

• postal: An address suitable for mailing

• former-anytype: A former (no longer valid) address of the specified type

Type	extensibleEnumeration

address: verified

Whether the address has been verified, typically by delivery of a token that is subsequently confirmed by the subject.

Type

boolean

assurance

A URI that asserts compliance with specific standards for identity assurance.

Plural	assurances
Type	string

citizenship

Country of citizenship of the subject.

Plural	citizenships
Type	country

dateOfBirth

Date of birth of the subject.

Plural	datesOfBirth
Type	date

emailAddress

An electronic mail address.

Plural	emailAddresses
Type	complex
Subattributes	address, type, verified

emailAddress: address

The email address. The expected value of this attribute is a string in RFC5322 addr-spec style (eg: foo@university.edu).

Type

string

emailAddress: type

EmailAddress type. Defined values are

• delivery: An emailAddress valid within the organization that represents an actual, deliverable mailbox. An emailAddress of this type might not be known to the subject it belongs to.

• department: The subject’s emailAddress for a department (ie: a sub-entity) of the organization

• department-deptlabel: The subject’s emailAddress for the department identified by deptlabel

• forwarding: The subject’s forwarding emailAddress (ie: the location where the subject would prefer to receive email)

• official: The official emailAddress assigned by the organization for the subject

• personal: The subject’s personal emailAddress, which need not be managed by the organization

• preferred: The subject’s self-declared preferred emailAddress

• former-anytype: A former (no longer valid) emailAddress of the specified type

Type	extensibleEnumeration

emailAddress: verified

Whether the emailAddress has been verified, typically by delivery of a token that is subsequently confirmed by the subject.

Type

boolean

entitlement

A URI that indicates a set of rights to specific resources.

Plural	entitlements
Type	string

ethnicity

The ethnicity of the subject. The default values for this attribute are as per the US Census Bureau. These values may not be suitable for use outside of US federal reporting requirements.

• africanAmerican

• alaskaNative

• americanIndian

• asian

• hispanic

• nativeHawaiian

• other

• pacificIslander

• white

Plural	ethnicities
Type	extensibleEnumeration

gender

Gender of the subject, self asserted. Defined values are

• female

• male

• nonBinary

Type	extensibleEnumeration

identifier

An identifier.

Plural	identifiers
Type	complex
Subattributes	identifier, type

identifier: identifier

The identifier.

Type

string

identifier: type

Identifier type. Defined values are

• applicant: Identifier assigned to an applicant (eg: student application registration system)

• badge: Identifier as encoded on a badge/physical ID card

• badge-barcode: Identifier as encoded on a 1D or 2D barcode printed on a badge

• badge-chip: Identifier as stored on a smart chip (contact or NFC) embedded in a badge

• badge-magstripe: Identifier as encoded on a magnetic stripe of a badge

• enterprise: Persistent identifier used to uniquely identify an individual across the enterprise/organization

• external: Identifier assigned by an external (federated) system

• national: Government issued identifier (eg: SSN)

• network: Identifier used for access to network services (eg: NetID)

• orcid: ORCID iD

• reference: An ID Match reference identifier

• role: Persistent identifier for a given role, used by an individual system of record and/or registry

• role-label: Persistent identifier for a given role assigned by the system of record identified by label

• sor: Persistent identifier used by an individual system of record

• sor-label: Persistent identifier assigned by the system of record identified by label

• former-anytype: A former (deprecated or no longer in use) identifier of the specified type

Type	extensibleEnumeration

identityDocument

A representation of an identity document, as (eg) might be used for identity proofing.

Plural	identityDocuments
Type	complex
Subattributes	dateOfBirth, documentIssuer, documentType, fullName, status, timeVerified, verifiedAddress

identityDocument: dateOfBirth

Date of birth, as confirmed on the identity document.

Type

date

identityDocument: documentIssuer

Name of agency issuing the identity document.

Type

string

identityDocument: documentType

Type of document used to confirm identity. Defined values are

• birthCertificate: Birth certificate

• driversLicense: Photo ID used to license drivers

• local: ID issued by a local government (such as cities or towns)

• national: ID issued by a national government, other than drivers licenses or passports

• nonDriver: ID as issued by DMV or equivalent

• passport: Passport, including Passport Cards

• regional: ID issued by a regional government (such as states or provinces), other than drivers licenses

• residency: ID indicating residency permission, such as a US Green Card

• selfAssertion: Identity information as self asserted

• tribal: ID issued by a tribal government (such as Native American tribes)

• visa: Visa, as typically attached to a Passport

Type	extensibleEnumeration

identityDocument: fullName

Full name, as confirmed on the identity document.

Type

string

identityDocument: status

Status of the identity document.

• expired: The document has expired

• invalid: The document is not valid, for a reason other than expiration

• valid: The document is valid

Type	extensibleEnumeration

identityDocument: timeVerified

When the identity document was verified.

Type

dateTime

identityDocument: validFrom

Date identity document is valid from, as asserted by the document itself.

Type

date

identityDocument: validThrough

Date identity document is valid through, as asserted by the document itself.

Type

date

identityDocument: verifiedAddress

Physical address, as confirmed on the identity document.

Type

string

member

Indication of a group membership. This attribute may be used either within a group object (in order to represent the members of the group) or within any other type of object (in order to represent the group of which the subject is a member). In either case, the value is an identifier suitable for resolving to the appropriate object.

Plural	members
Type	string

meta

The meta attribute is reserved for representation of attribute or record metadata.

name

A name for the subject.

Plural	names
Type	complex
Subattributes	family, formatted, given, language, middle, prefix, suffix, type

name: family

The subject’s family name, excluding any given, middle, or honorific components.

Type

string

name: formatted

The subject’s fully formatted name, localized for the selected language.

Note	This field should preferably be populated based on the subject’s self asserted preference, however when that is not possible formatting should respect the relevant name order, and any other conventions.

Type

string

name: given

The subject’s given name, excluding any middle, family, or honorific components. When a subject has only one name, it should typically be placed in this attribute.

Important

The term given can be problematic for members of certain communities, who may wish to identify by a chosen name rather than one assigned to them. Unfortunately, a better alternative label for this attribute has not been identified. Terms such as first name or forename imply word order, which causes confusion in an internationalized context (where family name, for example, may be written first). A term such as chosen is not well established, and could cause confusion in the context of an official name vs a preferred name. The use of the term given in the Attribute Dictionary must not be interpreted to include any implication of who gave the name to the person. The name could, for example, be self-given. Furthermore, like all attributes in the Attribute Dictionary, the attribute name is intended as a wire or protocol level definition. User interfaces should carefully consider terminology rendered for end users, and select context appropriate representations.

Type

string

name: language

The language encoding of this name.

Type

locale

name: middle

The subject’s middle name, excluding any given, family, or honorific components.

Type

string

name: prefix

The honorific prefix of the subject’s name, such as "Dr" or "Hon".

Type

string

name: suffix

The honorific suffix of the subject’s name, such as "Jr" or "III".

Type

string

name: type

The type of this name. Defined values are

• author: Name suitable for publishing (eg: on academic papers)

• fka: "Formerly Known As", a previous name for the person (eg: maiden name)

• official: Name as found on government-issued ID

• preferred: Name as self-asserted

Type	extensibleEnumeration

photo

Encoding of a photo of the subject.

Plural	photos
Type	complex
Subattributes	data, encoding, type

photo: data

Encoding of the subject’s photo.

Type

binary

photo: encoding

The type of encoding used for the subject’s photo. Defined values are

• bmp

• gif

• jpg

• png

• tiff

Type	extensibleEnumeration

photo: type

The type or purpose of the photo, not the encoding. Defined values are

• badge: Photo used on an ID card

• official: Photo taken for official purposes (such as display in a faculty directory)

• personal: User supplied photo for non-official purposes

Type	extensibleEnumeration

primaryAffiliation

The primary affiliation for the person, as defined by the organization.

Type

string

primaryCampus

The primary campus location for the person, as defined by the organization.

Type

string

primaryDepartment

The primary department for the person, as defined by the organization.

Type

string

primaryDepartmentCode

The primary department for the person, as represented as a machine readable identifier. This value is unlikely to have meaning outside of a specific organization.

Type

string

pronouns

Pronouns as asserted by the subject. The initial recommendation is to use the form they/them/their, however it is possible (or even likely) that representation of pronouns may evolve over time, and deployers are advised that recommendations for this attribute may similarly evolve over time.

Tip	It is recommended that the word preferred NOT be used in user interfaces managing pronouns.

Type

string

residency

Country of residency of the subject.

Plural	residencies
Type	country

role

A representation of the subject’s role or association with the organization.

Plural	roles
Type	complex
Subattributes	address, affiliation, campus, campusCode, department, departmentCode, displayTitle, emailAddress, identifier, leaveBegins, leaveEnds, manager, organization, organizationCode, percentTime, rank, rankSor, roleBegins, roleEnds, sor, sponsor, status, telephoneNumber, terminationReason, title, type, url, validFrom, validThrough

role: address

Address(es) associated with this role. This attribute uses the same definition for address as described above, including subattributes.

role: affiliation

The subject’s broad relationship to the organization, for this role. Values as originally defined in eduPerson, but may be extended.

• affiliate: A subject whose affiliation with the organization is not reflected by any other defined value.

• alum: A subject designated as alumni by the organization.

• applicant: A subject applying to the organization for any affiliation type.

• employee: A subject who is paid by the organization for work.

• faculty: A subject with an instructional or research responsibility for the organization.

• library-walk-in: A subject granted permissions based on physical presence.

• member: A member in good standing of the organization, including all subjects with a faculty, staff, student, or employee affiliation.

• researcher: A subject with research responsibilities for the organization.

• staff: A subject with work responsibilities other than instructional or research.

• student: A subject designated as student by the organization.

• enrolled-student: A subject enrolled in one or more classes offered by the organization.

• graduate-student: A subject enrolled in a post-Baccalaureate learning program, including those resulting in professional degrees.

• nondegree-student: A subject enrolled in a learning program that does not result in the award of a degree.

• registered-student: A subject registered to enroll in one or more classes of the organization.

• undergraduate-student: A subject enrolled in a learning program that is intended to result in the award of an Associates, Bachelors, or other similar degree.

Type	extensibleEnumeration

role: campus

The campus location this role is attached to, as defined by the organization.

Plural	campuses
Type	string

role: campusCode

The campus location this role is attached to, as defined by the organization and represented as a machine readable identifier. This value is unlikely to have meaning outside of a specific organization.

Plural	campusCodes
Type	string

role: department

The name of the department this role is attached to.

Plural	departments
Type	string

role: departmentCode

The department this role is attached to, as represented as a machine readable identifier. This value is unlikely to have meaning outside of a specific organization.

Plural	departmentCodes
Type	string

role: displayTitle

The display title for this role.

Type

string

role: emailAddress

Email Address(es) associated with this role. This attribute uses the same definition for emailAddress as described above, including subattributes.

role: identifier

Identifier(s) associated with this role. This attribute uses the same definition for identifier as described above, including subattributes.

role: leaveBegins

Time at which leave from this role begins. If both this attribute and role: status are provided, role: status is controlling.

Type

dateTime

role: leaveEnds

Time after which leave from this role is no longer in effect. If both this attribute and role: status are provided, role: status is controlling.

Type

dateTime

role: manager

An identifier describing the manager for this role. This attribute uses the same definition for identifier as described above, including subattributes, except that the name of the attribute is manager.

Plural

managers

role: organization

The name of the organization or institution this role is attached to.

Plural	organizations
Type	string

role: organizationCode

The organization or institution this role is attached to, as represented as a machine readable identifier. This value is unlikely to have meaning outside of a specific organization.

Plural	organizationCodes
Type	string

role: percentTime

The percentage time for this role, from 0 (no time allocated) to 100 (full time). Any value from 1 to 99 should be considered "part time".

Type

integer

role: rank

The rank of this role relative to all roles from all Systems of Record. The highest rank is 1, larger numbers indicate lower ranks.

Type

integer

role: rankSor

The rank of this role relative to only roles from this System of Record. The highest rank is 1, larger numbers indicate lower ranks.

Type

integer

role: roleBegins

Time at which this role officially begins. If both this attribute and role: status are provided, role: status is controlling.

Type

dateTime

role: roleEnds

Time after which this role is no longer in effect. If both this attribute and role: status are provided, role: status is controlling.

Type

dateTime

role: sor

Label identifying the System of Record authoritative for this role.

Type

string

role: sponsor

An identifier describing the sponsor for this role. This attribute uses the same definition for identifier as described above, including subattributes, except that the name of the attribute is sponsor.

Plural

sponsors

role: status

Status associated with this role.

• accepted: The subject has accepted an offer for this role (enrollment or hire)

• applied: The subject has applied for this role (enrollment or hire)

• active: The role is active (hire)

• offered: The subject has been made an offer for this role but has not yet accepted (enrollment or hire)

• onLeave: The subject is on leave from this role (enrollment or hire)

• registered: The subject has registered for this role (enrollment)

• suspended: The subject has been suspended from this role (enrollment or hire)

• terminated: The role has been terminated (enrollment or hire) (termination date is in [roleEnds])

Type	extensibleEnumeration

role: telephoneNumber

Telephone Number(s) associated with this role. This attribute uses the same definition for telephoneNumber as described below, including subattributes.

role: terminationReason

Reason for termination of this role.

• deceased

• graduated

• involuntary

• resigned

• retired

• withdrew

Type	extensibleEnumeration

role: title

The official title for this role.

Type

string

role: type

The type associated with this role.

• consultant

• continuing (student)

• contractor

• emeritus

• exempt

• graduate (student)

• nondegree (student)

• professional (student)

• regular

• secondary (student)

• summer (student)

• tenured

• undergraduate (student)

• vendor

• visiting

• workStudy

role: url

URL(s) associated with this role. This attribute uses the same definition for url as described below, including subattributes.

role: validFrom

Time at which services associated with this role should begins. If both this attribute and role: status are provided, role: status is controlling.

Type

dateTime

role: validThrough

Time after which services associated with this role should be terminated. If both this attribute and role: status are provided, role: status is controlling.

Type

dateTime

status

Status of the subject.

• accepted: The subject has accepted an offer for this role (enrollment or hire)

• applied: The subject has applied for this role (enrollment or hire)

• active: The subject is active

• offered: The subject has been made an offer for this role but has not yet accepted (enrollment or hire)

• onLeave: The subject is on leave from this role (enrollment or hire)

• registered: The subject has registered for this role (enrollment)

• suspended: The subject has been suspended from this role (enrollment or hire)

• terminated: The role has been terminated (enrollment or hire) (termination date is in [roleEnds])

Type	extensibleEnumeration

telephoneNumber

Telephone number for the subject.

Plural	telephoneNumbers
Type	complex
Subattributes	number, type, verified

telephoneNumber: number

Telephone number, preferably in E.164 notation.

Type

string

telephoneNumber: type

The type of the telephone number. Defined values are

• campus: The subject’s on campus telephone number

• fax: The subject’s fax machine

• home: The subject’s home telephone number

• mobile: The subject’s mobile telephone number

• office: The subject’s work or office telephone number

• summer: The subject’s summer time telephone number

• former-anytype: A former (no longer valid) telephone number of the specified type

Type	extensibleEnumeration

telephoneNumber: verified

Whether the telephone number has been verified, typically by delivery of a token that is subsequently confirmed by the subject.

Type

boolean

test

Whether this record represents a test entry.

Type

boolean

url

URL for the subject.

Plural	urls
Type	complex
Subattributes	url, type

url: url

URL for the subject.

Type

string

url: type

The type of the url. Defined values are

• official: Organizational URL

• personal: User supplied URL for non-official purposes

Type	extensibleEnumeration

References

1. eduPerson

2. ITU E.164 International Public Telecommunication Numbering Plan

3. ISO 639 ISO Language Codes

4. ISO 3166 ISO Country Codes

5. ISO 8601 ISO Date and Time Representations

Changelog

v1.0.0

• Initial release.