Skip to content

UUIDs in JSON files

All JSON configuration files for course instances, assessments and questions must contain a UUID (universally unique identifier) to link the on-disk JSON file to the corresponding object in the database. This looks like:

{
  "uuid": "cef0cbf3-6458-4f13-a418-ee4d7e7505dd"
}

When you create new questions, assessments, or course instances without using the PrairieLearn Web interface, you will need to add a UUID to the JSON file. These can be generated by https://www.uuidgenerator.net or other similar tools (UUID version does not matter).

While UUIDs in PrairieLearn are typically unique (and we recommend using unique UUIDs), their uniqueness is only enforced within their enclosing context:

  • Questions must have unique UUIDs within the same course.
  • Course instances must have unique UUIDs within the same course.
  • Assessments must have unique UUIDs within the same course instance.
  • Student labels must have unique UUIDs within the same course instance.

Different courses can reuse the same UUIDs without issue, and assessments in different course instances can share UUIDs.

When do you need a new UUID?

As your course is constructed, you may run into scenarios that require you to change the UUID listed within a JSON file. Below, we've listed some common instances of when the UUID should or shouldn't be changed.

  • Editing information within a JSON file: no new UUID needed. For example, if you delete a question in an infoAssessment.json, then you must not change the UUID. This is because PrairieLearn uses the UUID to know that it's still the same assessment, and you just want to make a change to it. If you do inadvertently change the UUID in this way, changing it back will revert everything to the way it was with no data loss.
  • Renaming a directory: no new UUID needed. For example if you rename a question or assessment directory, then you should leave the UUID the same, so that PrairieLearn will know that this is the same object but just with a new name.
  • Moving a directory: no new UUID needed. For example, if you move an assessment between course instances or if you move a question between courses, you can leave the UUID as is. You can also rename it in this case, but it isn't necessary.
  • Copying a directory within the same course or course instance: needs a new UUID. For example, if you copy an existing question or course instance to make a new one within the same course, then you will need a new UUID for the new object, so that PrairieLearn can distinguish it from the original. Similarly, copying an assessment within the same course instance will require a new UUID.
  • Copying a directory to a different course or course instance: no new UUID needed. For example, if you copy a question or course instance to a different course, the UUID can remain unchanged. Similarly, copying an assessment between course instances does not require a new UUID. In all of these cases, changing the UUID won't hurt, but also isn't needed.