A newer version of the Ed-Fi ODS / API is now available. See the Ed-Fi Technology Version Index for a link to the latest version.

Descriptor Mapping

As an Ed-Fi platform host, you may be called up on to support management of Descriptor Mappings. These mappings provide an operational context to the descriptor enumerations: the value X for namespace Y is equivalent to the value A in namespace B. Typically, a source system API client would be the one managing these Descriptor Mappings. However, there is a circumstances where you as a platform host may need to intervene first.

These mappings can be restricted to specific domain entities. The domain entities that can be used in the restriction are themselves Descriptors. Thus, the domain entity descriptors need to exist before creating descriptor mappings. And Descriptors are typically managed by the Platform Host. Here is a simple example, allowing studentSchoolAttendanceEvent to be used in a mapping:

POST /data/v3/ed-fi/modelEntityDescriptors

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

Referential Integrity

Please note that the Ed-Fi Unifying Data Model (UDM) does not create a formal relationship between a Descriptor Mapping and the Descriptors. Implication: someone can submit a Descriptor Mapping for a Descriptor that does not exist.

Some platform hosts might desire to enforce referential integrity here. A community member submitted the following SQL statement for creating a foreign key relationship. At this time, the Ed-Fi Alliance does not plan to add this as a fixed aspect of the ODS/API, preferring to leave platform hosts with greater flexibility.

ALTER TABLE edfi.Descriptor
ADD CONSTRAINT Unique_Namespace_CodeValue
UNIQUE ([Namespace], [CodeValue])

ALTER TABLE edfi.DescriptorMapping
ADD CONSTRAINT FK_DescriptorMapping_Descriptor_Must_Exist
FOREIGN KEY ([Namespace], [Value]) REFERENCES edfi.Descriptor([Namespace], [CodeValue]);

ALTER TABLE edfi.DescriptorMapping
ADD CONSTRAINT FK_DescriptorMapping_MappedDescriptor_Must_Exist
FOREIGN KEY ([MappedNamespace], [MappedValue]) REFERENCES edfi.Descriptor([Namespace], [CodeValue]);