Page History

Principles

1. TIER API specifications follow SCIM conventions on syntax and semantics unless specific and documented alternatives are called out
2. Some TIER APIs may be defined as profiles of SCIM-defined APIs
3. TIER Resource Type specifications follow SCIM conventions on schema definition and extension processes, syntax and semantics
4. Some TIER resource types may be defined as profiles of SCIM resource types

Pros:

1. In the case of messages that carry a representation of a resource, they should share the data structure and schema of its API counterpart.

Benefits of following these principles:

1. Freedom to define new resource types and schema and/or use existing SCIM resource types and schema
2. TIER APIs and schema can be generated Full SCIM compliance: Can be accomplished in conformance with SCIM RFCs using SCIM-defined procedures for defining new Resource Types and their core schema.
3. Freedom to define our own resource types and schema and/or use existing SCIM resource types and schema
4. Existing SCIM clients can access SCIM-profiled TIER resources and attributes without modification
5. SCIM SDKs and libraries may be partially reusable in for implementing TIER APIs

Cons and other issues:

Further guidance

1. For each TIER-defined resource type, ensure that all required To support SCIM User and Group objects, TIER would need to provide bi-directional, automated mapping between the TierUser and TierGroup schema and the corresponding SCIM schema. 
2. Q: Does that mean we still do prefixing in naming these objects?
3. A: No, I'd say when converting objects to SCIM, we'd ditch all the TIER ResourceType attributes that don't have a direct counterpart in SCIM. That way SCIM endpoints would see pure SCIM.
4. Q: Can we fix issues with SCIM e.g. that we want to offer a better way to page through large resultsets?
5. A: Since we declare TIER a superset of SCIM, we could define points on which TIER APIs diverge from SCIM APIs, but I think we should set a pretty high bar for deciding it's necessary to do that. If there's something wrong with SCIM, we should first really try to get it fixed in the next release of SCIM.  In general, better lines of communication with the SCIM community is a good thing.
6. Q: Does this mean we can't add things to the Meta object?  We are back to having a Meta and a TierMeta for Tier resource types?
A: If we just make sure all the SCIM meta attributes have a direct counterpart in the meta element we define for each TIER Resource Type, then we just need one meta object. Mapping from a TIER Resource Type to a SCIM Resource Type is then a straight mapping of corresponding attributes, plus filtering out all the TIER-specific meta elements.
7. Comment: We don't need to do the mapping. We can if we think there is value in doing so.
8. This solves the problem of TIER wanted to pepper the object model with new attributes, but what about when institutions want to add new attributes, they will have to either define institution specific resource types which is a lot of work or follow the scim extension model which is clunky.
   1. Response: Worth discussing. I'm inclined to say that for TIER-defined Resource Types we should allow local implementations to supplement the TIER schema at will with locally-defined attributes but insist that they prefix those attributes in a way that minimizes the chance of clashing definitions. That can be accomplished by requiring the 2nd-level component of the local domain name (the part just to the left of .edu) as a prefix. This isn't guaranteed to work for non-edu sites, so there are corner cases to keep an eye on. Then mapping from a local resource representation down to 'Pure TIER' or 'Pure SCIM' can be accomplished with a well-defined and simple filtering rule.
   2. Local implementations can do what they want, but adding attributes would break SCIM compliance.  The new attributes would not be in the resource schema specification.  One of the advantages of adopting a standard, in addition to having little documentation to do ourselves, is that we can take advantage of already written applications and libraries that work with the standard.  A quick search found several libraries for SCIM and Python.  One of which defines a "EnterpriseUser" resource.  So we are not the first to propose this. Whether or not undocumented attributes would break anything is unknown.
   3. Since it is we who control the schema, allowing institutions to propose formal additions should not be out of the question.
   4. Comment: What exactly is "clunky" about the extension mechanism in this use case? For TIER API as a whole it is problematic because we need to "redefine" a bunch of attributes, but for campus extensions this shouldn't happen. (Or else the campus should do the same thing and create a CampusPerson or whatever.) So is it just that the attribute label is lengthy? Perhaps we need a convention for extending complex attributes?
9. TIER meta element
10. To add Institution-level schema elements to TIER-defined resource types, follow the SCIM-defined schema extension methods
11. Define Internet2 Trust and Identity processes for self-registration of resource types and their schema: :everage Open API 2.0 and some API Manager, Developer PortalSome call this a con, some say pro, but you would have /TierUser and /User, /TierGroup, and /Group
12. There is duplication here, might be more to implement, might have drift between the object models
My contention is that we do not have /TierUser and /User, /TierGroup, and /Group.  In fact, in our API we have only EduPeople and EduGroups, and EduMembers (to use the new names).  Our API does not have Users or Groups.  It may be a service would add support for those SCIM core resources, but it wouldn't have to.  The two are separate APIs.  We might try to keep our resources as supersets of the scim core ones, to help sites that want to support both, but we wouldn't have to.
Response: +1, The 'Edu' prefix has the advantage of giving TIER complete control over its resource schema. The 'superset of SCIM' idea minimizes the effort needed to map Tier resource representations to SCIM and vice versa.