Overview

Meadowlark documents have a baseline standardized shape or scheme in data storage; however, some implementation details may vary by data storage provider. For example, the MongoDB implementation includes two arrays inside the document, which are stored as separate tables in PostgreSQL.

Also see:
Meadowlark - MongoDB
Meadowlark - PostgreSQL,
Meadowlark - Durable Change Data Capture

Standard Elements

[
  {
    "key": "localEducationAgencyId",
    "value": "2231"
  }
]

[
  {
    "localEducationAgencyId": "2231",

    "nameOfInstitution": "Grand Bend School District",
    "localEducationAgencyCategoryDescriptor": 

        "uri://ed-fi.org/LocalEducationAgencyCategoryDescriptor#Independent",
    "categories": [ ]
  }
]

Document Identifiers

Meadowlark items have two unique identifiers:

• The id  (aka "Meadowlark ID") value is a computed value based on the data standard version and data model natural key.
• The documentUuid is a v4 UUID (unique identifier) that is assigned at the time the item is first created in the API.

Early on in project Meadowlark, the application only used the computed id value above. This value makes it trivial to lookup a item in the data store, including for validating that a new item's references actually exist. It was also useful for allowing API clients to specify a particular resource to GET, PUT, or DELETE (e.g. GET /ed-fi/localEducationAgency/ZAwidGBEGsnKxQ-V1ktoecnvJ8xceXjM1jMehQ ).

It suffers from one glaring problem though: the natural key can change for some resource types. Implication: a changing natural key would change the id  value and thus break any external client integrations that stored that calculated ID. Thus the application needs a fully stable identifier for external usage. This external ID is the randomly/uniquely assigned documentUuid that does not change even if the natural key changes.

The following sequence diagram shows the differing internal and external uses of these two unique identifiers.

Meadowlark ID

The Meadowlark ID has a one-to-one unique match with the document, based on the data model project name, the resource name, and the natural key value(s). Because this could be rather large for some resources - for example, a StudentSectionAssociation resource - Meadowlark concatenates this information into a single string, calculates a hash value on it (using SHA3-224), and then encodes the result as a Base64 string. The keys are sorted alphanumerically before that concatenation, to guarantee a consistent ordering when there are multiple key fields.

Example: Course in the Ed-Fi Data Standard has a natural key composed of the courseCode  and the associated educationOrganization. The document identity is thus:

[
  {
    "key": "courseCode",
    "value": "span-101"
  },
  {
    "key": "educationOrganizationReference.educationOrganizationId",  
    "value": "123"
  }
]

To create a Meadowlark ID, the system concatenates this information into the following string and then hashes it:

Ed-Fi#Course#courseCode=span-101#educationOrganizationReference.educationOrganizationId=123