Early draft of TIER Core Schema for Systems of Record (SoR) and Entity Registry – from Benn Oshrin
There are no required attributes from the perspective of the Core Schema. It is up to a given protocol or implementation to determine what attributes are required, and how such status is conveyed between participants.
Where attributes are multi-valued, it is up to a given protocol or implementation as to whether multiple values are supported, and how such status is conveyed between participants.
Attribute names containing a slash (/
) may be represented "flat" as listed, or "hierarchical" by removing the slash and establishing a suitable representation in the encoding in use. For example, "name/given" could be represented in JSON as
{ "name":{ "given":"value" } }
Multiple values could be represented as
{ "identifiers":[ { "type":"enterprise", "value":"E12345678", }, { "type":"network", "value":"jqs123" } ] }
Attribute Release Policy
Attribute Release Policies are encoded in metadata, as described below. The following policies are defined:
public
: The attribute and value may be used without restriction.internal
: The attribute and value are to be used for official institutional purposes only, and may not be redistributed without permission.private
: The attribute and value may not be used for any purpose without permission.
Attribute Data Types
- binary
- boolean
- country: ISO 3166-1 two letter country code
- date: YYYY-MM-DD format (ISO 8601)
- dateTerm: A datestamp used to indicate intervals such as a semester, trimester, or quarter. The general 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: YYYY-MM-DDTHH:MM:SSZ format (ISO 8601)
- integer
- locale: LL_CC format (ISO 639-1 two letter language code, an underscore, ISO 3166-1 two letter country code)
- region: ISO 3166-2 subdivision code, not including country prefix (eg:
BC
notCA-BC
) - string: Strings are case-preserving but not case-sensitive
- extensibleVocabulary: The Core Schema vocabulary should be supported when described values are relevant, however implementations may add to the vocabulary. How supported values are conveyed between participants is outside of the scope of this document. Extended vocabulary must begin with
x-
.
Case Sensitivity
All attribute names and other elements specified here are case sensitive. eg: official
and OFFICIAL
are not the same.
Metadata
Any complex attribute (Person, Person Role, Address, Identifier, etc) may optionally have the following meta attributes:
meta/created
: Timestamp of record creation, in dateTime formatmeta/id
: Identifier for this specific (sub)attributemeta/lastModified
: Timestamp of last modification, in dateTime formatmeta/release
: Attribute release policy, as described above
Person Core Attributes
Attribute | Data Type | Definition | Multi-Valued? (Parent Attribute) |
---|---|---|---|
|
|
| Yes ( |
| country | Country from a postal address | One per parent object |
| string | Address rendered as a single string, possibly with embedded newlines ( | One per parent object |
| string | Locality information from a postal address (city, etc) | One per parent object |
| locale | The language encoding of the address | One per parent object |
| string | Postal code from a postal address | One per parent object |
| region | Region information from a postal address (state, province, etc) | One per parent object |
| string | Room information from a postal address | One per parent object |
Changing to | string (multi-line) | Street/site information from a postal address (street name, house number, etc) | One per parent object |
| extensibleVocabulary:
| The type of the address | One per parent object |
| boolean | True if the address has been verified | One per parent object |
| country | Country of citizenship of the person | Yes ( |
| date | The date of birth of the person | No |
|
|
| Yes ( |
| string | The email address | One per parent object |
| extensibleVocabulary:
| The type of the email address | One per parent object |
| boolean | True if the address has been verified | One per parent object |
| extensibleVocabulary:
| The ethnicity of the person (US Census) | Yes ( |
| extensibleVocabulary:
| The gender of the person | No |
|
|
| Yes ( |
| string | The identifier | One per parent object |
| extensibleVocabulary:
| The type of the identifier
| One per parent object |
|
|
| Yes ( |
| date | Date of birth, as confirmed on document | One per parent object |
| string | Name of agency issuing the confirmation document | One per parent object |
| extensibleVocabulary:
| Type of document used to confirm identity
| One per parent object |
| string | Full name, as confirmed on document | One per parent object |
| extensibleVocabulary:
| Status of the identity proofing | One per parent object |
| dateTime | Time document was confirmed | One per parent object |
| string | Address, as confirmed on document | One per parent object |
|
|
| Yes ( |
| string | The component of the person's name excluding the given, middle, and honorific components | One per parent object |
| string | The person's name, suitably formatted for display | One per parent object |
| string | The component of the person's name excluding the middle, family, and honorific components | One per parent object |
| locale | The language encoding of the person's name | One per parent object |
| string | The component of the person's name excluding the given, family, and honorific components | One per parent object |
| string | The honorific prefix of the person's name, such as "Dr" or "Ms" | One per parent object |
| string | The honorific suffix of the person's name, such as "Jr" or "III" | One per parent object |
| extensibleVocabulary:
| The type of the name
| One per parent object |
|
|
| Yes ( |
| binary | Encoding of a photo of the person | One per parent object |
| extensibleVocabulary:
| The encoding used for the photo | One per parent object |
| extensibleVocabulary:
| The type of the photo (not the encoding)
| One per parent object |
| string | The primary affiliation for the person, as defined by the institution (values same as for Person Role affiliation attribute, below) | No |
| string | The primary campus location for the person, as defined by the institution | No |
|
| Parent attribute for Role attributes, described below | Yes |
|
|
| Yes ( |
| string | Telephone number for the person, preferably in + notation | One per parent object |
| extensibleVocabulary:
| The type of the telephone number | One per parent object |
| boolean | True if the telephone number has been verified | One per parent object |
| boolean | True if this record represents a test entry | No |
|
|
| Yes ( |
| string | URL for the person | One per parent object |
| extensibleVocabulary:
| The type of the telephone number | One per parent object |
| extensibleVocabulary:
| Visa status of the person | No |
Person Role Core Attributes
Attribute | Data Type | Definition | Multi-Valued? |
---|---|---|---|
|
| As defined for Person Attributes | Yes ( |
| extensibleVocabulary:
| The person's broad relationship to the institution for the role (eduPerson) | One per role |
| string | The campus location this role is attached to, as defined by the institution | Yes ( |
campusCode | string | Machine readable identifier for a campus. This value is unlikely to have meaning outside of a specific institution. | Yes (campusCodes ) |
| string | The name of the department the role is attached to (multiple values are permitted if multiple departments sponsor a single role) | Yes ( |
departmentCode | string | Machine readable identifier for a department. This value is unlikely to have meaning outside of a specific institution. | Yes (departmentCodes ) |
| string | The display title for this role | One per role |
|
| As defined for Person Attributes | Yes ( |
|
| As defined for Person Attributes | Yes ( |
| dateTime | Time at which leave from this role begins; advisory – | One per role |
| dateTime | Time after which leave from this role is no longer in effect; advisory – | One per role |
| string | An identifier (preferably of type This should become a complex attribute (identifier+type) | Yes ( |
| string | The name of the organization/institution the role is attached to (multiple values are permitted if multiple organizations sponsor a single role) | Yes ( |
organizationCode | string | Machine readable identifier for an organization. This value is unlikely to have meaning outside of a specific institution. | Yes (organizationCodes ) |
| integer (0 - 100) | The percentage time for this role (100 = full time) | One per role |
| positive integer | The rank of this role relative to all roles from all SORs (highest rank = 1) | One per role |
| positive integer | The rank of this role relative to_ only_ roles from this SOR (highest rank = 1) | One per role |
| dateTime | Time at which the role officially begins | One per role |
| dateTime | Time after which the role is officially no longer in effect | One per role |
| string | Label for the system of record asserting this role | One per role |
| string | An identifier (preferably of type This should become a complex attribute (identifier+type) | Yes ( |
| extensibleVocabulary:
| Status associated with this role:
| One per role |
|
| As defined for Person Attributes | Yes ( |
| extensibleVocabulary:
| Reason for termination associated with this role | One per role |
| string | The official title for this role | Yes ( |
|
| As defined for Person Attributes | Yes ( |
| dateTime | Time at which services associated with the role should begin | One per role |
| dateTime | Time after which services associated with the role should be terminated | One per role |
HR Person Role Attributes
Attribute | Data Type | Definition | Multi-Valued? |
---|---|---|---|
| extensibleVocabulary:
|
| No |
Student Person Role Attributes
Attribute | Data Type | Definition | Multi-Valued? |
---|---|---|---|
| extensibleVocabulary:
|
| No |
courseAffiliation | extensibleVocabulary:
| Person's affiliation/role with a course. Based on MACE-Dir work. | Yes, per-courseMembership |
| string |
| Yes |
| extensibleVocabulary:
|
| Yes, if a single program generates more than one degree. (Otherwise use separate roles.) |
major | Yes (majors ) | ||
major/major | string | Student's major | No |
major/majorCode | string | Machine readable identifier for the major. This value is unlikely to have meaning outside of a specific institution. | No |
major/type | extensibleVocabulary
| No | |
| string |
| No |
studentType | extensibleVocabulary:
| Secondary = (eg) high school | No |
term | dateTerm | Term for which this record applies | No |
College/School should be expressed in organization
and Major/Program should be expressed in department
. (XXX or should they get dedicated attributes?)
Extended Attributes
The Core Schema may be extended. How extended attributes are conveyed between participants is outside of the scope of this document. Extended attributes must begin with x-
, may be hierarchical, and may be attached to the Person or Person Role.
Comments from Eric Goodman, Responses from Chris Hyzer
Challenging to comment on (especially on a fairly quick read!) So this is kind of a dartboard throw of questions and comments as I read through.
- General note: this construction would seem to put a fairly strict set of requirements on the actual registry repository. Yes, it’s possible to convert, but these structures and hierarchies are pretty specific in ways that would be more complex to abstract; it’s not just renaming values.
- Most of the attributes I’m looking at are defined with “ExtensibleVocabulary”. Is the idea that the “base” vocabulary is fixed (but extendable), or that the default vocabulary be ignored? I’m also concerned about the requirement for the “x-“ prefix on any extensions, but I understand the argument for it.
- ChrisH: I think that needs to be updated based on the TIER common elements document. Maybe just linked to it, no need to mention in each API
- For example, most campuses I’m aware of would call an ID a “Student ID”, not an “sor-studentsystem” ID. (Even though in many cases the latter might be a more accurate value.) Perhaps that could be handled with a simple rewrite rule on a ESB; I’d need to think about it more.
- On the Attribute Release Policies, is there any metadata associated with them? There are many attributes that will have “well understood” (well, supposedly well understood) campus release/usage policies associated with them. Does this model provide a mechanism to expand them if necessary?
- Is the idea that SSN is encoded as “identifier/type=national” (and presumedly “ARP=private”)? Would take getting my head around that approach, where each ID has its own ARP but they are all grouped together as a single list. Should consider a mechanism for vaulting these. Hashing is generally not useful (security wise, though maybe it is compliance wise), encrypting impacts your ability to do matching. Not sure what to do here, but I don’t think just having SSN sitting there is a good idea.
- Mentioned elsewhere, I don’t like that the only conditions on roles are start and end dates. But it seems like “roles” in this context are really “affiliations”, and other roles of the authZ type would perhaps be outsourced to, e.g., Grouper? In any case, if affiliation is what’s meant, the limitation is less concerning (and also, additional conditions could be added in the future).
- Not clear on the intent of “manager”. Is it equivalent to “supervisor”?
Comments from Tom Jordan
On the TIER SoR-Registry Core Schema:
- Provided there is a mechanism for extending attributes, I believe that base attributes and extended attributes can coexist. I would envision that Wisconsin would both supplement the existing role types and create new ones, but for the most part I believe that we can successfully map to the existing core attributes. I do envision a number of other types of roles that could be represented and possible attribute name conflicts (for example ‘department’ relating to both employment, affiliate, emeritus, etc) so unless the role is encapsulated in a data structure that disambiguates, they may need to be prefixed or named differently.
- Unless I’m misunderstanding the model, some of the person role core attributes tied to the person object are perhaps more appropriate to roles. For us at least, attributes like manager, organization, and department are going to be specific to a person’s job, and of course they may have more than one. Likewise for campus codes when we roll up into our systemwide identity registry.
- I think the registry model needs to be able to provide non-normalized storage of role information as well (for example, student information as expressed in the SIS vernacular) so that connected systems at least have the capability to retrieve and consume source-specific terms that may need to correlate to terms in other campus systems. This could perhaps be achieved through extended attributes in the current structure, but may require more complex data structures that would suggest that having the ability to declare a different role type (or a branch beneath an existing role type) might be better.
- I like the idea of metadata regarding attribute release on a per-complex-attribute basis. Would it be possible to extend this model to all attributes? Some of the attributes that are most likely to require privacy controls (address, email, etc) are not listed as complex.
Tom