impierce / digital-credential-data-models

Rust library for the several digital credential data models such as OpenBadges v3.0 and European Learner Model (ELM)

Credential data models

This repository will contain the following data models:

• Open Badges (v3)
• Elm (v3.2)

OpenBadges

Rust library for the Open Badges data model https://www.imsglobal.org/spec/ob/v3p0

Open Badges Specification Candidate Final Public Spec Version: 3.0 Document Version: 1.0.10 Date Issued: September 22, 2023

Summary

This library contains all structs and enums needed to (De)Serialize OpenBadges from and into JSON format. These structs and enums are enhanced with implementations and builders for more convenient usage.

Index

• src: This folder contains all the structs, enums and their implementations and builders.
• tests/obv3_json_examples: This folder contains all JSON format examples specified on the website (https://www.imsglobal.org/spec/ob/v3p0#examples-0) as JSON files.
• tests/tests: This folder contains the tests indexed per example JSON file.

Deviation

There is one deviation to the Json Schema as specified in the following issue: 1EdTech/openbadges-specification#553 Changes suggested in this issue are accepted, but have not yet been made. This library has already adopted this change.

digital-credential-data-models's Issues

[Request] A simple way to deserialize enums with types

Description

Types may sometimes need to on the struct as well as being used for deserialization on enums.

Motivation

Serde provides two possible ways to deal with enums: tag, and untagged.

With tag it will remove the "type" field from the JSON object and sets the enum correctly, however the struct behind the enum has no more type so it will fail.

Untagged won't remove the "type" but it will look at all possible combination of fields to test if one is correct. And fail on the enum if something is wrong.

A fix is needed which will look at the "type" field like in tag, but won't remove the "type" field from the JSON and will continue to parse.

Requirements

1. Create a derive macro that will implement deserialize manually
2. Add these derive macro on all enums which need it
3. Profit

Code example where current structure goes wrong

#[derive(Clone, Debug, Serialize, EnumDeserialize)]
#[serde(untagged)]
pub enum AgentOrPersonOrOrganisation {
    Agent(Box<Agent>),
    Person(Box<Person>),
    Organisation(Box<Organisation>),
}

#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct Agent {
    #[serde(rename = "additionalNote", default, skip_serializing_if = "Option::is_none")]
    pub additional_note: Option<ObjectOrVector<Note>>,
    #[serde(rename = "altLabel", default, skip_serializing_if = "Option::is_none")]
    pub alt_label: Option<ManyLangStringType>,
    #[serde(rename = "contactPoint", default, skip_serializing_if = "Option::is_none")]
    pub contact_point: Option<ObjectOrVector<ContactPoint>>,
    #[serde(rename = "dateModified", default, skip_serializing_if = "Option::is_none")]
    pub date_modified: Option<DateTimeType>,
    #[serde(rename = "groupMemberOf", default, skip_serializing_if = "Option::is_none")]
    pub group_member_of: Option<ObjectOrVector<Group>>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub id: Option<GenericIdType>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub identifier: Option<ObjectOrVector<IdentifierOrLegalIdentifier>>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub location: Option<ObjectOrVector<Location>>,
    #[serde(rename = "prefLabel", default, skip_serializing_if = "Option::is_none")]
    pub pref_label: Option<ManyLangStringType>,
    #[serde(rename = "type")]
    pub type_: String,
}

With #[serde(untagged)] every possible scenario will be checked. So if in struct agent in IdentifierOrLegalIdentifier there is an error is will discard the option the Object could be an Agent. Because it will look at which enum version match correctly.

With #[serde(tagged)] it will match the agent enum type and removes the "type" field from the JSON. So in this case Agent will crash because it can't fill the type_ string. A hack can be used like Option<> for type but then serializing won't be the same.

Are you planning to contribute this in a PR?

Yes

Restructure repository to contain multiple models

Description

The current repository only support one credential type. but we can restructure it to contain multiple.

Motivation

For the impierce mapper we want to be able to support multiple credential formats so its better to restructure this repo than create a new repo everytime a new version comes out

Resources

No response

To-do List

• Restructure repository into crates
• Create crate types-ob-v3
• Create crate types-elm-v3

Finetune builder implementations, deserialize with function to uphold certain OBv3 rules

Description

The large json schema reuses structs in several places, often with an intermediary enum: SingleItem,Vec. These enums do not yet have full implementations to keep the building pattern smooth.

Other than that some fields have mandatory entries. Mainly type with the mandatory entries: "VerifiableCredential" and "OpenBadgeCredential". We need to implement a deserialize with function that checks this.

Some structs also need a deserialize with function to check that at least one of the fields, which are all optional in these specific structs, are not empty, as the specs demand.

Motivation

Finetuning this OBv3 for rust library

Resources

https://www.imsglobal.org/spec/ob/v3p0

To-do List

• Item one
• Item two
• Item three