diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..fd6ae82 --- /dev/null +++ b/README.adoc @@ -0,0 +1,34 @@ += Internet2 Trust and Identity Schema + +:Email: hazelton@internet2.edu +:Date: 2018-07-18 +:Revision: 01 +:SelfLink: https://github.internet2.edu/TIER/schema +:Editor: Keith Hazelton +:Email: hazelton@internet2.edu + +[NOTE] +==== +Revision: {Revision} + +{Date} + +Self-link: {SelfLink} + +Editor: {Editor}, {Email} +==== + +== Minimal Registry Person + +==== link:issues.adoc[Current Issues] + +==== link:schema/core-person.json[Draft Core Person Schema (minimal registry person)] + * link:schema/tools.adoc[Schema Tools] + * Valid example person representations + ** link:data/person1.json[] + ** link:data/person2.json[] + +==== link:references.adoc[References] + +==== Starting Points: + + * link:schema/card.schema.json[] + * link:schema/card.schema.yml[] + * link:schema/gaborMinimalPersonSchema.yml[] diff --git a/tap-attribute-dictionary.adoc b/tap-attribute-dictionary.adoc new file mode 100644 index 0000000..ce05700 --- /dev/null +++ b/tap-attribute-dictionary.adoc @@ -0,0 +1,1270 @@ +TAP Attribute Dictionary +======================== +:Date: April 2021 +:Revision: v1.0.0 + +{revision} {date} + +Copyright (C) 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*: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2[ISO 3166-1] + two letter country code. +* *date*: Date in https://en.wikipedia.org/wiki/ISO_8601[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 https://en.wikipedia.org/wiki/ISO_8601[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 https://en.wikipedia.org/wiki/ISO_639-1[ISO 639-1] + language code, an underscore, and an https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2[ISO 3166-1] + two letter country code. +* *region*: http://en.wikipedia.org/wiki/ISO_3166-2[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]] +address +~~~~~~~ +A physical or postal address. +|=========================================================================== +|*Plural* |addresses +|*Type* |complex +|*Subattributes*|country, formatted, language, locality, postalCode, region, + room, streetAddress, type, verified +|=========================================================================== + +[[address-country]] +address: country +^^^^^^^^^^^^^^^^ +Country in which the address is located. +|========================= +|*Type* |country +|========================= + +[[address-formatted]] +address: formatted +^^^^^^^^^^^^^^^^^^ +Address rendered as a single string, possibly with embedded newlines (`\n`). +|========================= +|*Type* |string +|========================= + +[[address-language]] +address: language +^^^^^^^^^^^^^^^^^ +The language encoding of the address. +|========================= +|*Type* |locale +|========================= + +[[address-locality]] +address: locality +^^^^^^^^^^^^^^^^^ +Locality information from an address, such as a city name. +|========================= +|*Type* |string +|========================= + +[[address-postalCode]] +address: postalCode +^^^^^^^^^^^^^^^^^^^ +Postal code from an address. +|========================= +|*Type* |string +|========================= + +[[address-region]] +address: region +^^^^^^^^^^^^^^^ +Region information from an address, such as a state or province. +|========================= +|*Type* |region +|========================= + +[[address-room]] +address: room +^^^^^^^^^^^^^ +Room from an address. +|========================= +|*Type* |string +|========================= + +[[address-streetAddress]] +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 +^^^^^^^^^^^^^ +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]] +address: verified +^^^^^^^^^^^^^^^^^ +Whether the address has been verified, typically by delivery of a token that is +subsequently confirmed by the subject. +|========================= +|*Type* |boolean +|========================= + +[[assurance]] +assurance +~~~~~~~~~ +A URI that asserts compliance with specific standards for identity assurance. +|=========================================================================== +|*Plural* |assurances +|*Type* |string +|=========================================================================== + +[[citizenship]] +citizenship +~~~~~~~~~~~ +Country of citizenship of the subject. +|=========================================================================== +|*Plural* |citizenships +|*Type* |country +|=========================================================================== + +[[dateOfBirth]] +dateOfBirth +~~~~~~~~~~~ +Date of birth of the subject. +|=========================================================================== +|*Plural* |datesOfBirth +|*Type* |date +|=========================================================================== + +[[emailAddress]] +emailAddress +~~~~~~~~~~~~ +An electronic mail address. +|=========================================================================== +|*Plural* |emailAddresses +|*Type* |complex +|*Subattributes*|address, type, verified +|=========================================================================== + +[[emailAddress-address]] +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 +^^^^^^^^^^^^^^^^^^ +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]] +emailAddress: verified +^^^^^^^^^^^^^^^^^^^^^^ +Whether the emailAddress has been verified, typically by delivery of a token +that is subsequently confirmed by the subject. +|========================= +|*Type* |boolean +|========================= + +[[entitlement]] +entitlement +~~~~~~~~~~~ +A URI that indicates a set of rights to specific resources. +|=========================================================================== +|*Plural* |entitlements +|*Type* |string +|=========================================================================== + +[[ethnicity]] +ethnicity +~~~~~~~~~ +The ethnicity of the subject. The default values for this attribute are as per +the https://www.census.gov/topics/population/race/about.html[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 +~~~~~~ +Gender of the subject, self asserted. Defined values are + +* *female* +* *male* +* *nonBinary* + +|=========================================================================== +|*Type* |extensibleEnumeration +|=========================================================================== + +[[identifier]] +identifier +~~~~~~~~~~ +An identifier. +|=========================================================================== +|*Plural* |identifiers +|*Type* |complex +|*Subattributes*|identifier, type +|=========================================================================== + +[[identifier-identifier]] +identifier: identifier +^^^^^^^^^^^^^^^^^^^^^^ +The identifier. +|========================= +|*Type* |string +|========================= + +[[identifier-type]] +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]] +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]] +identityDocument: dateOfBirth +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Date of birth, as confirmed on the identity document. +|========================= +|*Type* |date +|========================= + +[[identityDocument-documentIssuer]] +identityDocument: documentIssuer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Name of agency issuing the identity document. +|========================= +|*Type* |string +|========================= + +[[identityDocument-documentType]] +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]] +identityDocument: fullName +^^^^^^^^^^^^^^^^^^^^^^^^^^ +Full name, as confirmed on the identity document. +|========================= +|*Type* |string +|========================= + +[[identityDocument-status]] +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]] +identityDocument: timeVerified +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +When the identity document was verified. +|========================= +|*Type* |dateTime +|========================= + +[[identityDocument-validFrom]] +identityDocument: validFrom +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Date identity document is valid from, as asserted by the document itself. +|========================= +|*Type* |date +|========================= + +[[identityDocument-validThrough]] +identityDocument: validThrough +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Date identity document is valid through, as asserted by the document itself. +|========================= +|*Type* |date +|========================= + +[[identityDocument-verifiedAddress]] +identityDocument: verifiedAddress +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Physical address, as confirmed on the identity document. +|========================= +|*Type* |string +|========================= + +[[member]] +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]] +meta +~~~~ +The _meta_ attribute is reserved for representation of attribute or record +metadata. + +[[name]] +name +~~~~ +A name for the subject. +|=========================================================================== +|*Plural* |names +|*Type* |complex +|*Subattributes*|family, formatted, given, language, middle, prefix, suffix, + type +|=========================================================================== + +[[name-family]] +name: family +^^^^^^^^^^^^ +The subject's family name, excluding any given, middle, or honorific components. +|========================= +|*Type* |string +|========================= + +[[name-formatted]] +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]] +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]] +name: language +^^^^^^^^^^^^^^ +The language encoding of this name. +|========================= +|*Type* |locale +|========================= + +[[name-middle]] +name: middle +^^^^^^^^^^^^ +The subject's middle name, excluding any given, family, or honorific components. +|========================= +|*Type* |string +|========================= + +[[name-prefix]] +name: prefix +^^^^^^^^^^^^ +The honorific prefix of the subject's name, such as "Dr" or "Hon". +|========================= +|*Type* |string +|========================= + +[[name-suffix]] +name: suffix +^^^^^^^^^^^^ +The honorific suffix of the subject's name, such as "Jr" or "III". +|========================= +|*Type* |string +|========================= + +[[name-type]] +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]] +photo +~~~~~ +Encoding of a photo of the subject. +|=========================================================================== +|*Plural* |photos +|*Type* |complex +|*Subattributes*|data, encoding, type +|=========================================================================== + +[[photo-data]] +photo: data +^^^^^^^^^^^ +Encoding of the subject's photo. +|========================= +|*Type* |binary +|========================= + +[[photo-encoding]] +photo: encoding +^^^^^^^^^^^^^^^ +The type of encoding used for the subject's photo. Defined values are + +* *bmp* +* *gif* +* *jpg* +* *png* +* *tiff* + +|========================= +|*Type* |extensibleEnumeration +|========================= + +[[photo-type]] +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]] +primaryAffiliation +~~~~~~~~~~~~~~~~~~ +The primary affiliation for the person, as defined by the organization. + +|========================= +|*Type* |string +|========================= + +[[primaryCampus]] +primaryCampus +~~~~~~~~~~~~~ +The primary campus location for the person, as defined by the organization. +|=========================================================================== +|*Type* |string +|=========================================================================== + +[[primaryDepartment]] +primaryDepartment +~~~~~~~~~~~~~~~~~ +The primary department for the person, as defined by the organization. +|=========================================================================== +|*Type* |string +|=========================================================================== + +[[primaryDepartmentCode]] +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 +~~~~~~~~ +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]] +residency +~~~~~~~~~ +Country of residency of the subject. +|=========================================================================== +|*Plural* |residencies +|*Type* |country +|=========================================================================== + +[[role]] +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]] +role: address +^^^^^^^^^^^^^ +Address(es) associated with this role. This attribute uses the same definition +for <
> as described above, including subattributes. + +[[role-affiliation]] +role: affiliation +^^^^^^^^^^^^^^^^^ +The subject's broad relationship to the organization, for this role. Values as +originally defined in https://wiki.refeds.org/display/STAN/eduPerson+2020-01#eduPerson2020-01-eduPersonAffiliation[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]] +role: campus +^^^^^^^^^^^^ +The campus location this role is attached to, as defined by the organization. +|========================= +|*Plural* |campuses +|*Type* |string +|========================= + +[[role-campusCode]] +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]] +role: department +^^^^^^^^^^^^^^^^ +The name of the department this role is attached to. +|========================= +|*Plural* |departments +|*Type* |string +|========================= + +[[role-departmentCode]] +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]] +role: displayTitle +^^^^^^^^^^^^^^^^^^ +The display title for this role. +|========================= +|*Type* |string +|========================= + +[[role-emailAddress]] +role: emailAddress +^^^^^^^^^^^^^^^^^^ +Email Address(es) associated with this role. This attribute uses the same +definition for <> as described above, including subattributes. + +[[role-identifier]] +role: identifier +^^^^^^^^^^^^^^^^ +Identifier(s) associated with this role. This attribute uses the same definition +for <> as described above, including subattributes. + +[[role-leaveBegins]] +role: leaveBegins +^^^^^^^^^^^^^^^^^ +Time at which leave from this role begins. If both this attribute and +<> are provided, <> is controlling. +|========================= +|*Type* |dateTime +|========================= + +[[role-leaveEnds]] +role: leaveEnds +^^^^^^^^^^^^^^^ +Time after which leave from this role is no longer in effect. If both this +attribute and <> are provided, <> is controlling. +|========================= +|*Type* |dateTime +|========================= + +[[role-manager]] +role: manager +^^^^^^^^^^^^^ +An identifier describing the manager for this role. This attribute uses the same +definition for <> as described above, including subattributes, +except that the name of the attribute is _manager_. +|========================= +|*Plural* |managers +|========================= + +[[role-organization]] +role: organization +^^^^^^^^^^^^^^^^^^ +The name of the organization or institution this role is attached to. +|========================= +|*Plural* |organizations +|*Type* |string +|========================= + +[[role-organizationCode]] +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]] +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]] +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]] +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]] +role: roleBegins +^^^^^^^^^^^^^^^^ +Time at which this role officially begins. If both this attribute and +<> are provided, <> is controlling. +|========================= +|*Type* |dateTime +|========================= + +[[role-roleEnds]] +role: roleEnds +^^^^^^^^^^^^^^ +Time after which this role is no longer in effect. If both this attribute and +<> are provided, <> is controlling. +|========================= +|*Type* |dateTime +|========================= + +[[role-sor]] +role: sor +^^^^^^^^^ +Label identifying the System of Record authoritative for this role. +|========================= +|*Type* |string +|========================= + +[[role-sponsor]] +role: sponsor +^^^^^^^^^^^^^ +An identifier describing the sponsor for this role. This attribute uses the same +definition for <> as described above, including subattributes, +except that the name of the attribute is _sponsor_. +|========================= +|*Plural* |sponsors +|========================= + +[[role-status]] +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 <>) + +|========================= +|*Type* |extensibleEnumeration +|========================= + +[[role-telephoneNumber]] +role: telephoneNumber +^^^^^^^^^^^^^^^^^^^^^ +Telephone Number(s) associated with this role. This attribute uses the same +definition for <> as described below, including subattributes. + +[[role-terminationReason]] +role: terminationReason +^^^^^^^^^^^^^^^^^^^^^^^ +Reason for termination of this role. + +* *deceased* +* *graduated* +* *involuntary* +* *resigned* +* *retired* +* *withdrew* + +|========================= +|*Type* |extensibleEnumeration +|========================= + +[[role-title]] +role: title +^^^^^^^^^^^ +The official title for this role. +|========================= +|*Type* |string +|========================= + +[[role-type]] +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]] +role: url +^^^^^^^^^ +URL(s) associated with this role. This attribute uses the same definition for +<> as described below, including subattributes. + +[[role-validFrom]] +role: validFrom +^^^^^^^^^^^^^^^ +Time at which services associated with this role should begins. If both this +attribute and <> are provided, <> is controlling. +|========================= +|*Type* |dateTime +|========================= + +[[role-validThrough]] +role: validThrough +^^^^^^^^^^^^^^^^^^ +Time after which services associated with this role should be terminated. If +both this attribute and <> are provided, <> is +controlling. +|========================= +|*Type* |dateTime +|========================= + +[[status]] +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 <>) + +|========================= +|*Type* |extensibleEnumeration +|========================= + +[[telephoneNumber]] +telephoneNumber +~~~~~~~~~~~~~~~ +Telephone number for the subject. +|=========================================================================== +|*Plural* |telephoneNumbers +|*Type* |complex +|*Subattributes*|number, type, verified +|=========================================================================== + +[[telephoneNumber-number]] +telephoneNumber: number +^^^^^^^^^^^^^^^^^^^^^^^ +Telephone number, preferably in E.164 notation. +|========================= +|*Type* |string +|========================= + +[[telephoneNumber-type]] +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]] +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]] +test +~~~~ +Whether this record represents a test entry. +|=========================================================================== +|*Type* |boolean +|=========================================================================== + +[[url]] +url +~~~ +URL for the subject. +|=========================================================================== +|*Plural* |urls +|*Type* |complex +|*Subattributes*|url, type +|=========================================================================== + +[[url-url]] +url: url +^^^^^^^^ +URL for the subject. +|========================= +|*Type* |string +|========================= + +[[url-type]] +url: type +^^^^^^^^^ +The type of the url. Defined values are + +* *official*: Organizational URL +* *personal*: User supplied URL for non-official purposes + +|========================= +|*Type* |extensibleEnumeration +|========================= + +References +---------- +. https://wiki.refeds.org/display/STAN/eduPerson+2020-01[eduPerson] +. https://www.itu.int/rec/T-REC-E.164[ITU E.164] International Public + Telecommunication Numbering Plan +. https://www.iso.org/iso-639-language-codes.html[ISO 639] ISO Language Codes +. https://www.iso.org/iso-3166-country-codes.html[ISO 3166] ISO Country Codes +. https://www.iso.org/standard/70907.html[ISO 8601] ISO Date and Time + Representations + +Changelog +--------- +v1.0.0 +~~~~~~ +* Initial release.