diff --git a/README.md b/README.md index c828266..b9434f1 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,24 @@ # core-schema -TAP Core Schema + +## TAP Core Person Schema + +The [TAP Core Person Schema](tap-core-person-schema.adoc) defines a dictionary of common +attributes used across various components of the TAP portfolio. The +authoritative Core Schema is abstract -- it cannot be used directly, but is +best thought of as an *attribute library* that can be used to construct other +documents. + +The following types of documents are defined as part of the Core Schema library: + +* **Representations**: Mappings of the Core Schema to a specific form, such as + JSON, XML, or YAML. + * [TAP Core Person Schema: How to Create a JSON Representation](tap-core-person-schema-create-json-representation.adoc) (CS-JSON) + +* **Profiles**: Selections of Core Schema attributes for a particular purpose. + +* **Protocols**: A specification for implementation, based on a Representation + and perhaps a Profile. Of all the Core Schema documents, only Protocols are + actually implementable in software. + +As an example, the **eduPerson LDAP Schema** would be a *Protocol* that +references the *eduPerson Profile* and the *LDAP Representation*. diff --git a/tap-core-person-schema-create-json-representation.adoc b/tap-core-person-schema-create-json-representation.adoc new file mode 100644 index 0000000..d1b1714 --- /dev/null +++ b/tap-core-person-schema-create-json-representation.adoc @@ -0,0 +1,213 @@ +TAP Core Person Schema: How to Create a JSON Representation +=============================== +:Date: August 2020 +:Revision: v1.0.0 + +{revision} {date} + +Copyright (C) 2020 +University Corporation for Advanced Internet Development, Inc. + +About the JSON Representation +----------------------------- +The Core Schema JSON Representation describes how to represent Core Schema +attributes in JSON. For compactness, this document uses the term "CS-JSON" to +refer to the JSON Representation of the Core Schema. + +CS-JSON is represented as a JSON object, that is a pair of curly braces +surrounding zero or more JSON members. It is possible for (and perhaps even +expected that) a CS-JSON object to itself be embedded in a broader JSON +document, for example for message transport purposes. + +.Example CS-JSON Object +---- +{ + "meta": { + "id": "14874930-d274-4a1b-881a-3aee78235dbf", + "created": "2020-08-28T20:10:38Z", + "lastModified": "2020-08-29T03:17:55Z", + "release": "public" + } +} +---- + +Attribute Data Types +-------------------- +All Attribute Data Types defined in the Core Schema map to JSON strings, +except as follows: + +* *boolean*: Maps to JSON `true` or `false` +* *integer*: Maps to JSON _number_ + +Record Metadata +--------------- +Metadata attributes that apply to the entire record are defined in a JSON +member of the CS-JSON object, identified by the key `meta`, and consisting of +a JSON object whose key/value pairs are any Record Metadata attribute defined +in the Core Schema. + +.Example Record Metadata +---- +{ + "meta": { + "id": "5458879", + "lastModified": "2020-02-27T19:30:03Z" + }, + "attributes": { + ... + } +} +---- + +Attribute Representation +------------------------ +Within the CS-JSON object, each attribute key is the corresponding Core Schema +attribute. The plural name is used when the attribute may have multiple values, +regardless of whether or not multiple values are conveyed in any given +transaction. In other words, the attribute name _EmailAddresses_ is always +used even if only one email address is being sent across the wire. + +CS-JSON defines several different representations for attributes. It is up to +each Protocol to determine which formats to use in which context. + +Simple Attribute +~~~~~~~~~~~~~~~~ +A _Simple Attribute_ is a single key/value pair, where the value is an +appropriate JSON type (ie: neither an object nor an array). + +.Example Simple Attribute +---- +{ + "dateOfBirth": "1983-03-18" +} +---- + +Simple Attribute With Multiple Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To represent multiple values for a simple attribute, a JSON array is used +with the plural attribute name. + +.Example Simple Attribute With Multiple Values +---- +{ + "citizenships": [ + "CA", + "NL" + ] +} +---- + +Simple Attribute With Metadata +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Adding metadata to a simple attribute requires the use of a JSON object, which +will have two keys: _meta_ and _value_. _value_ is of an appropriate JSON type +(neither an object nor an array), while _meta_ is a JSON object holding the +desired metadata attributes. + +.Example Simple Attribute With Metadata +---- +{ + "dateOfBirth": { + "meta": { + "id": "179865", + "created": "2017-08-21T14:27:55Z", + "source": "sis" + } + "value": "1983-03-18" + } +} +---- + +Complex Attribute +~~~~~~~~~~~~~~~~~ +A _Complex Attribute_ is represented as a JSON object, whose members are +key/value pairs or, if appropriate, sub-objects. + +.Example Complex Attributes +---- +{ + "emailAddress": { + "address": "plee@university.edu", + "type": "official", + "verified": true + }, + "role": { + "affiliation": "faculty", + "address": { + "streetAddress": "127 University Drive", + "room": "305C", + "type": "office" + } + } +} +---- + +Complex Attribute With Multiple Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To represent multiple values for a complex object, a JSON array is used with +the plural attribute name. + +.Example Complex Attributes With Multiple Values +---- +{ + "names": [ + { + "given": "Patricia", + "family": "Lee", + "type": "official" + }, + { + "given": "Pat", + "family": "Lee", + "type": "preferred" + } + ] +} +---- + +Complex Attribute With Metadata +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Metadata can be added to complex attributes in two ways, depending on what the +metadata is intended to represent. A _meta_ block applied to the JSON object +itself applies to the entire complex attribute. Additionally, component +attributes may use the Simple Attribute With Metadata form to apply metadata +to each component. + +.Example Complex Attribute With Metadata +---- +{ + "emailAddress": { + "meta": { + "created": "2018-01-03T09:18:21Z", + "source": "selfservice" + } + "address": "plee@social.com", + "type": "preferred", + "verified": { + "meta": { + "source": "emaillink" + }, + "value": true + } + } +} +---- + +Ad Hoc Attributes +~~~~~~~~~~~~~~~~~ +Ad Hoc Attributes are namespaced using the namespace, a colon `:`, and the +attribute name. For example: `university.edu:provider`. Ad Hoc attributes may +be used anywhere a Core Schema attribute or subattribute may be used. + +.Example Ad Hoc Attributes +---- +{ + "emailAddress": { + "address": "plee@university.edu", + "type": "official", + "verified": true, + "university.edu:mailboxProvider": "OIT Exchange" + }, + "univerity.edu:campusTrainingLevel": "magenta" +} +---- diff --git a/tap-core-person-schema.adoc b/tap-core-person-schema.adoc new file mode 100644 index 0000000..c660e0e --- /dev/null +++ b/tap-core-person-schema.adoc @@ -0,0 +1,1066 @@ +TAP Core Person Schema +====================== +:Date: July 2020 +:Revision: v1.0.0 + +{revision} {date} + +Copyright (C) 2020 +University Corporation for Advanced Internet Development, Inc. + +About the Core Schema +--------------------- +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*: 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 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 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 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]] +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 +|========================= + +[[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 +|========================= + +[[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* + +|=========================================================================== +|*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 +* *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]] +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 + +* *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]] +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 +|========================= + +[[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-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. +|========================= +|*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 campus location 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 +|=========================================================================== + +[[pronouns]] +pronouns +~~~~~~~~ +Preferred pronouns of the subject. +|=========================================================================== +|*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 +per https://wiki.refeds.org/display/STAN/eduPerson+2020-01#eduPerson2020-01-eduPersonAffiliation[eduPerson], +but may be extended. + +* *affiliate* +* *alum* +* *employee* +* *faculty* +* *library-walk-in* +* *member* +* *staff* +* *student* + +|========================= +|*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 leave from 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 +|========================= + +[[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.