Managing Descriptor Mappings

Since Data Standard 4.0, the Ed-Fi Resource API has included a concept of Descriptor Mapping, wherein a descriptor value in one namespace is mapped to a different value in another namespace. This facilitates exchange of enumeration values. For example, at the local level one might track student absence very granularly (i.e. "absent with medical excuse"), but another system might only track "is absent" without caring about the reason. Then we can say that "absent with medical excuse" in the one system is equivalent to "is absent" in another system. With one catch: we will need to use the Descriptor code values found in the Ed-Fi API, which are likely simpler/shorter versions of the descriptions above. Example:

ABSENT-MED in namespace uri://gbisd.edu/AttendanceEventCategory has the same meaning as ABS in namespace  uri://ed-fi.org/AttendanceEventCategory.

This mapping can be restricted to certain entities or it can be applied universally. The following request creates a universal mapping that applies to all entities that have an AttendanceEventCategoryDescriptor :

POST /data/v3/ed-fi/descriptorMappings

{
  "mappedNamespace": "uri://ed-fi.org/AttendanceEventCategory",
  "mappedValue": "ABS",
  "namespace": "uri://gbisd.edu/AttendanceEventCategory",
  "value": "ABSENT-MED"
}

If you try this on a Ed-Fi ODS/API deployment with the default set of descriptors, then you'll encounter an authorization warning, for example:

{
  "message": "Access to the resource item could not be authorized based on the caller's NamespacePrefix claims: 'uri://ed-fi.org', 'uri://gbisd.org', 'uri://tpdm.ed-fi.org'."
}

This is because there is a typo in example above: it has gbisd.edu instead of gbisd.org. But it was a useful typo, in that it helped us understand something about authorization: you can only create mappings on authorized namespaces. We can try that again:

POST /data/v3/ed-fi/descriptorMappings

{
  "mappedNamespace": "uri://ed-fi.org/AttendanceEventCategory",
  "mappedValue": "ABS",
  "namespace": "uri://gbisd.org/AttendanceEventCategory",
  "value": "ABSENT-MED"
}

This version succeeds.

There are several different kinds of attendance events in the Ed-Fi Data Standard: students might be attending an Intervention, a Program, School, or a Section. Perhaps this mapping only applies for Section and School attendance events. We can alter the example above to restrict it  to only those two entities. That modification will use a new type of descriptor, called the modelEntityDescriptor . As with any other descriptor, you must first setup the system with the allowed list of model entities. While descriptor mappings are setup by source system API clients (e.g. a Student Information System), the allowed descriptors are usually configured by the platform host (e.g. the education organization, or a service provider on their behalf).

Below are two POST requests that prepare the system to accept Section and School attendance event entity names for descriptor mappings.

POST /data/v3/ed-fi/modelEntityDescriptors

{
  "codeValue": "studentSchoolAttendanceEvent",
  "description": "studentSchoolAttendanceEvent domain entity",
  "shortDescription": "studentSchoolAttendanceEvent",
  "namespace": "uri://ed-fi.org/modelEntityDescriptor"
}

##

POST /data/v3/ed-fi/modelEntityDescriptors

{

  "codeValue": "studentSectionAttendanceEvent",
  "description": "studentSectionAttendanceEventdomain entity",
  "shortDescription": "studentSectionAttendanceEvent",
  "namespace": "uri://ed-fi.org/modelEntityDescriptor"
}

Now that those have been added, we can restrict the mapping to apply only to these two entities:

POST /data/v3/ed-fi/descriptorMappings

{
  "mappedNamespace": "uri://ed-fi.org/AttendanceEventCategory",
  "mappedValue": "ABS",
  "namespace": "uri://gbisd.org/AttendanceEventCategory",
  "value": "ABSENT-MED",
  "modelEntities": [
    {
      "modelEntityDescriptor": "uri://ed-fi.org/modelEntityDescriptor#studentSchoolAttendanceEvent"
    },
    {
      "modelEntityDescriptor": "uri://ed-fi.org/modelEntityDescriptor#studentSectionAttendanceEvent"
    }
  ]
}

For more background on Descriptor Mapping, see The Past and Future of Ed-Fi Descriptors: Change is coming – Here’s What’s New and a (Longish) History of Why.