tap-attribute-dictionary.adoc

TAP Attribute Dictionary

v1.0.0 July 2020

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

About the TAP Attribute Dictionary

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

A Representation of the Core Schema 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 Core Schema.

About Core Schema Attributes

There are no required attributes from the perspective of the Core Schema. It is up to a given Protocol using the Core Schema 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.

Attribute Data Types

Core Schema 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 Core Schema 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 Core Schema 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 Core Schema 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 core schema 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 Core Schema).

Attribute Metadata

The following Metadata attributes are available:

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

• 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.

  • 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.

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

Record Metadata

The same attributes defined for Attribute Metadata may also be used for record metadata.

Core Schema 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

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

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

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

• referenceId: 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

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

• driversLicense: Photo ID used to license drivers

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

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

• passport: Passport, including Passport Cards

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

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

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

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: 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.

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 campus location 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

pronouns

Preferred pronouns of the subject.

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 per eduPerson, but may be extended.

• affiliate

• alum

• employee

• faculty

• library-walk-in

• member

• staff

• student

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 leave from 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

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.