Page Comparison

The following are common questions and solutions around the usage of Ed-Fi descriptors.

Contents

Which descriptors are most important for my organization's usage of Ed-Fi?

There are over 160 descriptors in the core Ed-Fi data model and many more in domains under development or proposed for introduction into the core model. Not all of them will be relevant to your organization's use of Ed-Fi.

Generally, the descriptors that matter most to your organization initially will be those involved in data exchanges between systems, so which matter will usually first depend on the APIs you . That list will generally depend on the APIs you organization is are using.

A good first list to pay attention to are the descriptors that are required in an Ed-Fi API certification, as these must be present in a data exchange. By API, those descriptors are:

It is unlikely you will need to consider or map all of these values, as your organization is likely not using all APIs covered in this standard. The lists by domain (see  Descriptor Guidance#DescriptorsbyDomain) can be cross-referenced with this list to further focus your efforts.

Do we have to use Ed-Fi-defined values?

The answer to this question is "no" but there may be reasons why you should attempt to stay within these values.

For clarity, no one is forced to use the Ed-Fi values. The Ed-Fi technologies and specifications are open source and can be used however desired. Plus, the Ed-Fi Alliance and its community have discovered over time and endorsed the notion that there is no set of code values for any concept (for example, for grade level) that is universally applicable (see below for more information on this). By definition, this means that we need to expect that code sets will sometimes be localized.

However, just because variation will exist and just because there is no "universally applicable" set of values for any concept, it does NOT follow that it is not helpful for us to adopt a common sets in some casescircumstances, and for the Alliance to encourage - – sometimes strongly encourage - – community members to adopt common values. When we act in common ways, then we can rely on each other, share resources, and interoperate with each other easier.

Said anther way: there may be pain or loss in mapping local values to Ed-Fi values, but that pain provides benefits in terms of interoperability.

Additional technical guidelines on custom descriptor values for users of the Ed-Fi Operational Data Store can be found in the Guidance on Code Values and Descriptors for LEAs.

In what ways does Ed-Fi encourage or enforce compliance with particular value sets?

First, as we noted above, any Ed-Fi descriptor set can be modified in implementation field work. 

However, in its API standards and certificationcertifications, the Ed-Fi Alliance does make specific add requirements for descriptor values. In order to be judged to be compliant with one of those specification, a product may be required to show that it can use a particular setsset. That set is generally (but not necessarily) a set defined by the Ed-Fi Data Standard.

As an example, you can see that the Assessment Outcomes API v3 requires usage of most Ed-Fi defined values, but makes a few exceptions: Ed-Fi Assessment Outcomes API for Suite 3 Certification#FiAssessmentOutcomesAPIforSuite3Certification-Enumerations.

Why do Ed-Fi descriptor values have a URL in them?

If you look at a descriptor in a Ed-Fi defined data packet in the APIserialization, you will see it has this format:

uri://ed-fi.org/AcademicSubjectDescriptor#Mathematics

This is the pattern followed:

[namespace]#[descriptor value]

If the value is stored in a database, you will often see this URL there as well (possibly in a separate column). This is the pattern followed:

[namespace]#[descriptor value]

namespace stored separately.

The descriptor value should be clear , but – it is the "code" that typically appears in source systems. But what is the namespace?  The namespace is a string value that tells you who governs or defines the value. In this case, you can see that the value "Mathematics" is defined by "ed-fi.org". In other words, the Ed-Fi Alliance defines a value called "Mathematics." If this was an agency with a different definition of mathematics, there could very well be a different descriptor value that looked like this:

uri://mydistrict.edu/AcademicSubjectDescriptor#Mathematics

This is telling you that this is "mydistrict.edu" definition of "Mathematics" and NOT not the definition of the Ed-Fi Alliance. (Also: strictly speaking: this namespace is not a URL.) 

By convention, these namespaces usually follow a URL-like-pattern, referencing an internet domain owned by the organization that governs the descriptor value.

How do I create my own descriptors?

Descriptors are simple to create - you – you just create the code value you need, and of course we . We recommend strongly that you define the value as well (we have not mentioned it thus far, but descriptors should have a clear definition).

However, the important part of creating a new descriptor value is that the value should be placed in your own namespace, and NOT not placed in the "ed-fi.org" namespace. For example, if you were at a school district called: Great Oaks School District and needed an Academic Subject value called "Linear Algebra II", your descriptor might look like this:

uri://greatoakssd.edu/AcademicSubjectDescriptor#Linear Algebra II

It is recommended but not required that the namespace you choose include a URL domain name that is under your organizations control and resolves to a web property owned by your organization. This helps those who see this value understand who created that value.