Discrepancies in the data for some terms in the context of different schema representations

[siuc-nate]

I was comparing the outputs (mostly the JSON-LD) of credreg for CTDL, CTDL-ASN, and QData, and I noticed that some terms show different information depending on which one of those JSON-LD files you're looking at. This is usually caused by the way the schema manager currently handles "borrowing" terms from one schema to show in the context of another schema.

A term is "borrowed" so that it will show up in a schema other than its own (e.g. so there will be a table for ceterms:name on the QData terms page), and by default it just gets borrowed as-is. This is done by creating an entry for a term from one schema in the list of terms for another schema and setting that entry's "BorrowedFromSchemaId" value to be the schema ID of the original schema. If the only values in that entry are the term's URI and the value for BorrowedFromSchemaId, then everything else will be read from the original schema's entry for that URI.

But the schema manager allows overwriting one or more attributes of a term within the context of that schema (so that, for example, ceterms:name could have a different domain depending on whether you were looking at the CTDL terms page or the QData terms page). That may have made sense at some point in the past (maybe there was a use case for it at the time), but I don't think it still does. In other words, the system is working as intended, and the data needs correction.

The only reason borrowing happens at all is mostly for the convenience of the user, so that the user doesn't have to click around between multiple terms pages as much. This behavior was created back when there was minimal borrowing of terms and it was manageable to keep up with it, but since it's such a common practice now, it might be better to remove borrowed entries completely after fixing the discrepancies listed below (though this would mean more navigating on the consuming end, it would also be less confusing).

Regardless of whether you remove borrowed entries or not, you'll need to fix the discrepancies listed in the table below. The process/solution is basically the same for each of them:

1. Ensure the canonical representation of the term in the appropriate schema[1] has the right data
   • Check the term history from each schema's representation of that term just in case a history entry was made in the non-original schema due to an overwrite being made in the non-original schema.
2. Remove any overwriting data from the representation of that term in other schemas.
3. Ensure the same fix gets applied to both the current release and the pending release so that the problem doesn't reappear when the pending release becomes current

[1] Since we don't have/use a standalone representation of schema.org terms, the below solutions assume that the CTDL schema (in the schema manager sense, not in an RDF sense) would fill that role. The schema manager does support adding such a representation, but that is probably more complexity than is needed here.

These are the issues I found when comparing the 3 JSON-LD documents linked above:

#	Issue	Fix	JSON-LD Term Links	History Links
1	QData overwrites the domain of ceterms:alternateName	Add any valid domains to the CTDL representation of ceterms:alternateName and remove the entire domain value from the QData representation of ceterms:alternateName	CTDL QData	CTDL CTDLASN QData
2	QData overwrites the domain of ceterms:name	Add any valid domains to the CTDL representation of ceterms:name and remove the entire domain value from the QData representation of ceterms:name	CTDL QData	CTDL CTDLASN QData
3	QData overwrites the domain of ceterms:description (and has an invalid value, "qdata:EarningsProfile")	Add any valid domains to the CTDL representation of ceterms:description and remove the entire domain value from the QData representation of ceterms:description	CTDL QData	CTDL CTDLASN QData
4	QData overwrites the domain of ceterms:endDate	Add any valid domains to the CTDL representation of ceterms:endDate and remove the entire domain value from the QData representation of ceterms:endDate	CTDL QData	CTDL CTDLASN QData
5	QData overwrites the domain of ceterms:startDate	Add any valid domains to the CTDL representation of ceterms:startDate and remove the entire domain value from the QData representation of ceterms:startDate	CTDL QData	CTDL CTDLASN QData
6	QData overwrites the domain of ceterms:jurisdiction	Add any valid domains to the CTDL representation of ceterms:jurisdiction and remove the entire domain value from the QData representation of ceterms:jurisdiction	CTDL QData	CTDL CTDLASN QData
7	QData overwrites the range of ceterms:processingAgent	Remove the entire domain value from the QData representation of ceterms:processingAgent (the CTDL representation already points at the 3 organization classes, and ceterms:Agent shouldn't be used as a range since that would be inconsistent with other properties)	CTDL QData	CTDL CTDLASN QData
8	CTDL-ASN overwrites the domain of ceterms:industryType	Add any valid domains to the CTDL representation of ceterms:industryType and remove the entire domain value from the CTDL-ASN representation of ceterms:industryType	CTDL CTDLASN	CTDL CTDLASN QData
9	CTDL-ASN overwrites the domain of ceterms:occupationType	Add any valid domains to the CTDL representation of ceterms:occupationType and remove the entire domain value from the QData representation of ceterms:occupationType	CTDL CTDLASN	CTDL CTDLASN QData
10	Both CTDL-ASN and QData overwrite the domain of ceterms:instructionalProgramType	Add any valid domains to the CTDL representation of ceterms:instructionalProgramType and remove the entire domain value from the CTDL-ASN and QData representations of ceterms:instructionalProgramType	CTDL CTDLASN QData	CTDL CTDLASN QData
11	The definition and usage note for schema:QuantiativeValue are mismatched between CTDL and QData	Determine what the correct definition and usage note (if any) should be, update it in the CTDL representation, set QData to borrow from that, and remove anything from the QData representation that would overwrite the CTDL representation.	CTDL QData	CTDL CTDLASN QData
12	The domain for schema:description is mismatched between CTDL and QData	Determine the correct domain, update it in the CTDL representation, set QData to borrow from that, and remove anything from the QData representation that would overwrite the CTDL representation.	Not available (conflicts with the URL for ceterms:description); find it in the full schema JSON-LD files linked above	CTDL CTDLASN QData
13	The usage note and domain for schema:maxValue are mismatched between CTDL and QData	Determine what the correct values for the domain and usage note (if applicable) should be, update the CTDL representation to match that, set QData to borrow from that, and remove anything from the QData representation that would overwrite the CTDL representation.	CTDL QData	CTDL CTDLASN QData
14	The usage note and domain for schema:minValue are mismatched between CTDL and QData	Determine what the correct values for the domain and usage note (if applicable) should be, update the CTDL representation to match that, set QData to borrow from that, and remove anything from the QData representation that would overwrite the CTDL representation.	CTDL QData	CTDL CTDLASN QData
15	The usage note and domain for schema:value are mismatched between CTDL and QData	Determine what the correct values for the domain and usage note (if applicable) should be, update the CTDL representation to match that, set QData to borrow from that, and remove anything from the QData representation that would overwrite the CTDL representation.	CTDL QData	CTDL CTDLASN QData
16	The definition and range for schema:unitText are mismatched between CTDL and QData	Determine what the correct values for the definition and range should be, update the CTDL representation to match that, set QData to borrow from that, and remove anything from the QData representation that would overwrite the CTDL representation. See also this comment/issue.	CTDL QData	CTDL CTDLASN QData

[philbarker]

Items 11-16, which concern terms borrowed from Schema.org, require more thought regarding how closely we should keep to the Schema.org definitions for these properties. Our policy is that we shouldn't change anything as it may lead to conflicts and confusion for anyone who is using both ceterms: and schema.org and already has the schema.org term definitions in their system. I also wonder why we use schema:description when we have ceterms:description declared as its equivalent.

[philbarker]

Proposed changes:

1. QData overwrites the domain of ceterms:alternateName

• In CTDL:

URI: ceterms:alternateName
Add to domain: ceterms:EarningsProfile, ceterms:EmploymentOutcomeProfile, qdata:DataSetProfile, qdata:DataSetTimeFrame

• In QDATA:

URI: ceterms:alternateName
Remove from domain: ceterms:EarningsProfile, ceterms:EmploymentOutcomeProfile, ceterms:Place qdata:DataSetProfile, qdata:DataSetTimeFrame

2. QData overwrites the domain of ceterms:name

• In CTDL :

URI: ceterms:name
Add to domain: ceterms:EarningsProfile ceterms:EmploymentOutcomeProfile qdata:DataSetProfile qdata:DataSetTimeFrame

• In QDATA:

URI: ceterms:name
Remove from domain: ceterms:EarningsProfile ceterms:EmploymentOutcomeProfile ceterms:Place qdata:DataSetProfile qdata:DataSetTimeFrame

3. QData overwrites the domain of ceterms:description (and has an invalid value, "qdata:EarningsProfile")

• In CTDL

URI: ceterms:description
Add to domain: ceterms:EarningsProfile ceterms:EmploymentOutcomeProfile ceterms:JurisdictionProfile ceterms:ProcessProfile qdata:DataProfile qdata:DataSetProfile qdata:DataSetTimeFrame

• In QDATA

URI: ceterms:description
Remove from domain: ceterms:EmploymentOutcomeProfile ceterms:JurisdictionProfile ceterms:ProcessProfile qdata:DataProfile qdata:DataSetProfile qdata:DataSetTimeFrame qdata:EarningsProfile

4. QData overwrites the domain of ceterms:endDate

• In CTDL

URI: ceterms:endDate
Add to domain: qdata:DataSetTimeFrame

• In QDATA

URI: ceterms:endDate
Remove from domain: qdata:DataSetTimeFrame

5: QData overwrites the domain of ceterms:startDate

• In CTDL

URI: ceterms:startDate
Add to domain: qdata:DataSetTimeFrame

• In QDATA

URI: ceterms:startDate
Remove from domain: qdata:DataSetTimeFrame

6: QData overwrites the domain of ceterms:jurisdiction

• In CTDL

URI: ceterms:jurisdiction
Add to domain: qdata:DataSetProfile

• In QDATA

URI: ceterms:jurisdiction
Remove from domain: qdata:DataSetProfile

7: QData overwrites the range of ceterms:processingAgent

(already OK - [ ] In CTDL)

• In QDATA

URI: ceterms:processingAgent
Remove from range: ceterms:Agent

8: CTDL-ASN overwrites the domain of ceterms:industryType

• In CTDL

URI: ceterms:industryType
Add to domain: ceasn:Competency

• In CTDL-ASN

URI: ceterms:industryType
Remove from domain: ceasn:Competency ceasn:CompetencyFramework

9: CTDL-ASN overwrites the domain of ceterms:occupationType

• In CTDL

URI: ceterms:occupationType
Add to domain: ceasn:Competency

• In CTDL-ASN

URI: ceterms:occupationType
Remove from domain: ceasn:Competency ceasn:CompetencyFramework

10: Both CTDL-ASN and QData overwrite the domain of ceterms:instructionalProgramType

• In CTDL

URI: ceterms:instructionalProgramType
Add to domain: qdata:DataSetProfile ceasn:Competency ceasn:CompetencyFramework

• In CTDL-ASN

URI: ceterms:instructionalProgramType
Remove from domain: ceasn:Competency ceasn:CompetencyFramework

• In QDATA

URI: ceterms:instructionalProgramType
Remove from domain: qdata:DataSetProfile

To Be Decided:
11 - 16.

[siuc-nate]

Remember, the combined history tracking (across all schema representations) for a given property will give you the canonical state that that property should have right now (with the caveat that no history tracking was entered for the very first release, so properties that are from back then will be missing some details and you'll need to look at the schema itself to see their state at that time). So if that combined history says the property should have the domain you want it to have, then no formal change proposal is necessary, as you are just correcting a detail of how that property is/was entered into the system.

If the history says something different from what it should be, then I think a formal change makes sense.

At least it should be that simple - but there is also the wrinkle of any cases where I made a mistake in entering something, such as with the first release of QData, which was a massive addition in general.

For example, if you will allow me to deep dive a bit, it looks like the alternateName changes came from that first QData release (they're there in the above JSON) even though they weren't all(?) documented in the history tracking. This comment from #844 back then shows it being added to Place and HoldersProfile (among others), and the comment from Mike afterwards suggests adding it to EarningsProfile and EmploymentOutcomeProfile. The additions to DataSetProfile and DataSetTimeFrame came after that comment as well, so I suspect what happened is that I made the entries from the first comment in CTDL as part of the normal workflow, and later came back and added the others in QData (for some reason) and must have forgotten to put them into the history tracking at the time. That would explain why HoldersProfile shows in the CTDL version (it was in the normal workflow comment) and the other domains show in the QData version (they were in the later comments). Notably, ceterms:Place is in both the CTDL representation and the QData representation - not sure why.

Which means that:

• The formal documentation (the github issue) above shows all of those as being valid domains for alternateName (which probably makes sense),
• The history tracking does not show all of those as being a valid domain (due to what I assume is my error), and
• What you see in the schema depends on which URL you're looking at (due to a limitation of the schema manager)

I think the closest of those to being correct in terms of our intent is the github issue, as that lines up with what the schema manager is (poorly) trying to show, so I think you can get away with adding those domains to alternateName in CTDL (and removing the domain field value in QData), as that will correctly reflect what the domain was supposed to be all along.

As for the others, I'd have to look through them to see if the situation goes that deep. Ideally you can just look at the history tracking across the schemas to see what the domains should be right now.

[philbarker]

Thanks @siuc-nate
As far as no formal change proposal being necessary, I wrote one mostly so that I would know what to do as a result of this issue (and to leave a record of what I did), even if the net effect is to make things what they should already be. That's just me being careful as it's the first big change I'll make. For similar reasons I'll probably make the change in pending first so that we can check it before it goes live.

[philbarker]

I also found:

• in QDATA:
  URI: ceterms:instructionalProgramType
  Remove from range: skos:Concept

[philbarker]

The above changes have all been made in Pending for QDATA, CTDL and CTDL-ASN and entered into the history log.

The domains/ranges are no longer being over-written.

The additions made to CTDL are not showing in the previews of the QDATA and CTDL-ASN terms, I guess because they import from the current CTDL and the additions were made to pending.

[siuc-nate]

I vaguely recall an issue where cross-schema references don't display properly when you're looking at the pending release (and what you're pulling from is also the pending release for its schema). I don't recall whether that was fixed, so that may well be the issue, yes.

[philbarker]

On the terms borrowed from schema.org... It's not optimal to publish anything that changes or adds to any part of a term definition for something borrowed from another namespace. Our namespace policy allows that we may add things like rangeIncludes, domainIncludes that suit our purpose internally, but is silent on publishing these changes. Ideally we wouldn't but in fact we do, and changing that may cause bigger issues with consumers who rely on us publishing the data. That's not ideal but not really part of this issue, and maybe we live with it.

The fixes to return the terms borrowed from the schema.org namespace to what they were intended to be are:

11 The definition and usage note for schema:QuantiativeValue are mismatched between CTDL and QData

• CTDL term is as intended.

• In QData

URI: schema:QuantitativeValue
Remove definition: Point value for cohort characteristics and other purposes.
Remove label: Quantitative Value
Remove Status: vs:stable
Add BorrowedFromSchemaIID: ctdl

12 The domain for schema:description is mismatched between CTDL and QData
(Setting aside for now the question of why we have schema:description when ceterms:description can be used in its place)

• In CTDL

URI schema:description
Add to domain: schema:MonetaryAmount

• QData

URI schema:description
Remove from domain: schema:MonetaryAmount
Remove definition: A description of the item.
Remove label: Description
Remove Status: vs:stable
Remove Range: rdf:langString
Add BorrowedFromSchemaId: ctdl

13 The usage note and domain for schema:maxValue are mismatched between CTDL and QData

• In CTDL

URI schema:maxValue
Add to domain: ceasn:CriterionLevel, schema:MonetaryAmount, qdata:Observation
Remove Usage Note: "For single values, use schema:value. For ranges, use schema:minValue and schema:maxValue."
Add Usage Note: "In CTDL: for single values, use schema:value; for ranges, use schema:minValue and schema:maxValue."

• In QDATA

URI schema:maxValue
Remove Label: Max Value
Remove description: Upper value of some characteristic or property.
Remove status: vs:stable
Remove from domain: ceasn:CriterionLevel, schema:MonetaryAmount, qdata:Observation
Remove range: xsd:float
Add BorrowedFromSchemaId: ctdl

14 The usage note and domain for schema:minValue are mismatched between CTDL and QData

• In CTDL

URI schema:minValue
Remove UsageNote: For single values, use schema:value. For ranges, use schema:minValue and schema:maxValue.
Add UsageNote: In CTDL: for single values, use schema:value; for ranges, use schema:minValue and schema:maxValue.
Add to domain: ceasn:CriterionLevel, schema:MonetaryAmount, qdata:Observation

• In QDATA

URI schema:minValue
Remove label: Min Value
Remove Description: Lower value of some characteristic or property.
Remove status: vs:stable
Remove from domain: ceasn:CriterionLevel, schema:MonetaryAmount, qdata:Observation
Remove from range: xsd:float
add BorrowedFromSchemaId: ctdl

15 The usage note and domain for schema:value are mismatched between CTDL and QData

• In CTDL

URI schema:value
Remove UsageNote: For single values, use schema:value. For ranges, use schema:minValue and schema:maxValue.
Add UsageNote: In CTDL: for single values, use schema:value; for ranges, use schema:minValue and schema:maxValue.
Add to domain: ceasn:CriterionLevel, schema:MonetaryAmount, qdata:Observation

• In QDATA

URI schema:value
remove label: Value
Remove definition: The value of the property value node.
remove status: vs:stable
Remove from domain: ceasn:CriterionLevel, schema:MonetaryAmount, qdata:Observation
Remove from range: xsd:float
Add BorrowedFromSchemaId: ctdl

16 The definition and range for schema:unitText are mismatched between CTDL and QData

The range for this is so different to that used in schema.org that we should be using our own term.

• In CTDL

URI schema:unitText
add to Domain: schema:MonetaryAmount
add to Range: skos:Concept

• In QDATA

URI schema:unitText
Remove label: Unit Text
Remove definition: "Word or phrase indicating the unit of measure."
Remove status: vs:stable
Remove from domain: schema:MonetaryAmount schema:QuantitativeValue
Remove from range: skos:Concept
Add BorrowedFromSchemaId: ctld