Social Finance Fund Companion Module version 2 - brief for developers

[mrgarth]

SFF Companion Module Version 2.0

This release of the Social Finance Fund (SFF) Companion Module v2.0 introduces significant breaking changes to enhance data modelling and consistency, primarily addressing awkward modelling of EquityDeservingGroup, PopulationServed, and Characteristic classes, as well as inconsistencies in code list development patterns.

The key solutions involve simplifying the data model by replacing sff:EquityDeservingGroup with cids:Characteristic and adhering to a consistent cids:Code and skos:Concept structure for code lists (taxonomies).

These issues and their proposed resolutions will introduce breaking changes for software and JSON-LD files aligned to previous versions of the SFF Companion Module. The “breaking” change is that some required classes/tables will have different rdf:types and different properties. Software aligned to Version 2 will not be backward compatible with older versions without additional measures to provide functionality for converting Version 1 files.

Issue 1: Modelling EquityDeservingGroup

The initial modelling issue stemmed from the differences between ontology constraints for context-free versus context-dependent classes, and from having separate code lists for PopulationServed and EquityDeservingGroup, despite one being a subset of the other. Both sff:EquityDeservingGroup and PopulationServed conceptually map well to the cids:Characteristic class, but were modelled as their own classes/lists in Version 1.

cids:Characteristic is a context-dependent class, meaning it may use properties with unique, organization-specific values. This risks data conflicts if the same URI is reused by multiple organizations. In Version 1, EquityDeservingGroup had issues with its ontology definition implying direct use of a code list for its URIs, despite being modelled as context-dependent, and with its hasCharacteristic property incorrectly pointing to instances of the context-dependent Characteristic class.

Solution: simplifying the model {#solution:-simplifying-the-model}

Version 2 resolves these issues with a simpler model that better utilizes the Characteristic and Code classes. The former role of the sff:EquityDeservingGroup table/class is now filled by the cids:Characteristic table/class, and sff:EquityDeservingGroup is removed.

• For SFF participants, the minimum requirement is that the properties for Characteristic are @id, @type, hasName, hasDescription, and hasCode, where @id, @type, and hasName are not blank.
• The @id value for a Characteristic must be in the user’s own domain/namespace and cannot reuse URIs from code lists.
• The hasCode property of Characteristic may now point to code list items from the updated PopulationServed code list, which now includes all items from the formerly separate EquityDeservingGroup code list and has properties consistent with cids:Code.

Changes to table structure and relationships

Table/class	How data is structured in Version 1	How data is structured in Version 2
OrganizationProfile	servesEDG links to EquityDeservingGroup primaryPopulationServed links to PopulationServed	primaryPopulationServed links to Characteristic
EquityDeservingGroup	hasCharacteristic links to Characteristic	(class/table removed)
Characteristic	hasCode links to PopulationServed Includes non-standard properties	hasCode links to PopulationServed (no change) Properties now consistent with standard definition.
PopulationServed (code list)	Does not distinguish the subset of items that are members of EquityDeservingGroup. Fields/properties inconsistent with cids:Code class.	The @type property indicates whether a code list item is an EquityDeservingGroup. Fields/properties are consistent with cids:Code class.
EDGProfile	forEDG links to EquityDeservingGroup	forEDG links to Characteristic

Implementation examples

Creating custom, user-defined entries in the Characteristics table

EXAMPLE: The fictional organization “Zero Waste Meal Kits” has an existing set of categories used to track historical board demographic data. They have data on the number of their Board members who identify as “men”, “women”, “trans men”, and “trans women”.

To set up a data model for their impact report that maps to their existing data collection, Zero Waste Meal Kits would create these four entries in their Characteristic table:

Table 1: Characteristic table example for user-defined categories

@id	hasName	hasDescription	hasCode
https://zerowaste.ca/Characteristic/men/	Men
https://zerowaste.ca/Characteristic/transmen/	Trans Men		https://codelist.commonapproach.org/PopulationServed#ps1
https://zerowaste.ca/Characteristic/women/	Women		https://codelist.commonapproach.org/PopulationServed#ps22
https://zerowaste.ca/Characteristic/transwomen/	Trans Women		https://codelist.commonapproach.org/PopulationServed#ps22, https://codelist.commonapproach.org/PopulationServed#ps1

• There is no hasCode entry for “Men” because there is no corresponding entry in the PopulationServed table that ESDC has identified as an Equity Deserving Group.
• “Trans Men” has used the code for PopulationServed item ps1, "2SLGBTQIA+", whose description is "People who identify as being two-spirit, lesbian, gay, bisexual, transgender, queer, intersex, asexual and others (“+”)."
• Both “Women” and “Trans Women” have been associated with PopulationServed item ps22, "Women (Cisgender and Transgender)".
• “Trans Women” has been coded as both ps1 and ps22.
• Descriptions are optional and have been left blank (Zero Waste Meal Kits does not have written descriptions for the categories).

Using ESDC’s categories for the Characteristics table

EXAMPLE: The fictional organization “Zero Waste Meal Kits” has no historical data about their Board composition. They will set up a data model for their impact report that uses the demographic data categories provided in the ESDC PopulationServed list:

Table 2: Characteristic table example for ESDC categories

@id	hasName	hasDescription	hasCode
https://zerowaste.ca/Characteristic/2SLGBTQIA (note the “+” has been removed)	2SLGBTQIA+	People who identify as being two-spirit, lesbian, gay, bisexual, transgender, queer, intersex, asexual and others (“+”)."	https://codelist.commonapproach.org/PopulationServed#ps1
https://zerowaste.ca/Characteristic/womenCisgenderTransgender	Women (Cisgender and Transgender)	All people who identify as women, whether they are cisgender or transgender women.	https://codelist.commonapproach.org/PopulationServed#ps22
https://zerowaste.ca/Characteristic/peopleOfAdvancedAge65Plus	People of Advanced Age (65+)	People who are 65 and older.
https://zerowaste.ca/Characteristic/physicalSensoryOrPainRelatedDisability	People Living with Physical, Sensory or Pain-Related Disabilities	People living with disabilities, impairments, and/or functional limitations [...]	https://codelist.commonapproach.org/PopulationServed#ps18, https://codelist.commonapproach.org/PopulationServed#ps27
… and so on, for any or all of the other Populations and/or Equity Deserving Groups for which they will collect data about Board members’ self-identification.

• In this case, the values for hasName and hasDescription are copied directly from the PopulationServed list entries, and the relevant URI is entered in hasCode.
• Note that the URIs have been written to conform to the general URI syntax defined in RFC 3986, only using uppercase and lowercase letters (A-Z, a-z), decimal digits (0-9), hyphen (-), period (.), underscore (_), and tilde (~). The “+” was removed from “2SLGBTQIA+” in the URI, as this is a reserved character with a special meaning in the context of URIs.
• “People of Advanced Age (65+)” is not an Equity Deserving Group by ESDC’s definition, but it can still be used as a demographic data category if organizations want to collect this data for their own purposes. The @type property in the PopulationServed class/table indicates whether or not an item is an Equity Deserving Group.
• Item ps18 “People Living with Physical, Sensory or Pain-Related Disabilities” is not directly a member of the Equity Deserving Group list. This is visible in the @type property of ps18 in the PopulationServed table. However, its skos:broader property identifies ps18 as a sub-item of ps27, “People Living with a Disability (including invisible and episodic disabilities)”, which is an Equity Deserving Group. Counting people identifying as ps18 as members of EquityDeservingGroup ps27 is technically feasible given this skos:broader relationship. However, it requires extra effort by analysts that cannot be guaranteed, and so it is recommended that Characteristics be explicitly mapped to Equity Deserving Groups using hasCode where applicable.

Issue 2: Code list consistency

The “breaking” change is that some taxonomies (“code lists”) may require different rdf:types, properties, or (worst case) a change in URI naming scheme before they can be expected to function properly when data is validated by SHACL and/or aggregated at the portfolio level.

Where possible, URIs will be maintained in updated code lists, and where this is not possible, “redirects” put in place to manage the differences between versions and minimize disruption for users.

The root of the issue: inconsistent development patterns

Code lists used with the SFF Companion module have not followed a consistent pattern of development and employ different naming conventions, structures, and vary in their use of taxonomy frameworks such as skos:ConceptScheme versus cids:Code.

The solution: adhering to cids:Code and skos:Concept structure

The proposed changes to address this are not specific to SFF, and affect all code lists for all users of the Common Impact Data Standard.

The PopulationServed list is the first code list to be updated, see https://codelist.commonapproach.org/PopulationServed.ttl.

Common Approach will update the other code lists shortly to mirror these changes to the codelist and item structure. We will provide a further update when these changes are complete and the new versions are live.