We need a way to represent or link to statements about / made by the content of a resource

[philbarker]

For the Agreements and Policies that govern transfer of prior learning we need a way of conveying the content of the agreement/policy. We have this need in other use cases as well. Often this all gets packed into the "description" even though there is a difference between a description of something and conveying part of the content or something, and at the cost of being unable to retrieve the details of what it was about.

Currently we have several pairs of properties like learningMethod & learningMethodDescription, processStandards & processStandardsDescription, where one property allows something to be described as a literal value and the other allows a link to a webpage providing more detail. This is somewhat inelegant.

A general utility class for making statements relevant to the resource being described, linking to where those statements are made in full / the authoritative source, and maybe classifying the statement / providing text that could be used as a header for it would be useful.

for example:
Use case: To represent the content of a transfer agreement we need to distinguish between the "purpose" of the agreement and the terms (obligations, conditions etc) it lays out.

Solution might look like:

{
    "@type": "ceterms:Agreement",
    "@id": "https://...",
    "ceterms:description": "Transfer value agreement between ... and ... ...",
    "ceterms:purpose": {
        "@type": "ceterms:StructuredStatement",
        "ceterms:statement": "The purpose of this agreement is to facilitate...",
    },
    "ceterms:mutualObligation: {
        "@type": "ceterms:StructuredStatement",
        "ceterms:name": "Indemnity"
        "ceterms:statement": "Both parties are required to ...",
    },
}

If the range of processStandards were set to ceterms:StructuredStatement rather than xsd:anyURI (and remember the current range is problematic), then they could be used to provide the data currently provided by learningMethodDescription and processStandardsDescription, e.g.

{  ...
    "ceterms:processStandards": {
        "@type": "ceterms:StructuredStatement",
        "ceterms:description":  "We adhere to recognized best practices including....",
        "ceterms:subjectWenpage": "http://..." 
}

[siuc-nate]

Interesting: Some initial thoughts/questions, in no particular order:

Would the Structured Statement's data be largely the same across many records? If so, it should probably be moved to its own standalone thing and given a CTID (it could just be a bnode for cases where it doesn't need to be externally referenced). That would also have the benefit of not needing to make a (breaking?) change to the range of processStandards et al, since you could just reference its URI.

Would the statement field need to support formatting (e.g. markdown)? The closer we get to copying the resource into the metadata about the resource, the more likely it is for that sort of thing to come up as well.

Are there other things that might need to go into the Structured Statement class down the road? It might be better to avoid using up the "ceterms:statement" URI out of the gate in case we need something more specific later. Perhaps "statementText" (to align with competencyText, assuming description doesn't work here)? If formatting is needed, maybe something like "formattedDescription"?

Would it be better to have a statementType property that could reference a concept scheme? That would allow publishers to invent their own statement types as needed rather than us needing to figure out individual new properties for every statement type that we encounter down the road.

Depending on answers to the above, could the agreement be characterized as a Collection with a list of Structured Statements as members?

Some examples:
First, one that shows the agreement as a collection with statements as bnode members with formatted text and a statementType that allows for a mix of CTDL-defined and publisher-defined concepts:

{
  "@graph": [
    {
      "@type": "ceterms:Collection",
      "@id": "https://.../ce-12345",
      "ceterms:classification": [ "collectionCat:TransferArticulationAgreement" ],
      "ceterms:description": { "en-us": "Transfer value agreement between..." },
      "ceterms:hasMember": [
        "_:abc",
        "_:def",
        "_:ghi"
      ]
    },
    {
      "@type": "ceterms:StructuredStatement",
      "@id": "_:abc",
      "ceterms:statementType": [ "statementCat:Purpose", "statementCat:Summary" ],
      "ceterms:formattedDescription": { 
        "en-us": "# Purpose
The purpose of this **agreement** is to...
- One
- Two
- Three
  - Three A
  - Three B
---
More text"
      },
      "ceterms:subjectWebpage": "https://some-uri"
    },
    {
      "@type": "ceterms:StructuredStatement",
      "@id": "_:abc",
      "ceterms:statementType": [ "statementCat:MutualObligation", "https://some-custom-type-of-statement-from-this-publisher" ],
      "ceterms:name": { "en-us": "Idemnity" },
      "ceterms:formattedDescription": {
        "en-us": "Both parties are **required** to ..."
      }
    },
    {
      "@type": "ceterms:StructuredStatement",
      "@id": "_:ghi",
      "ceterms:name": { "en-us": "Bespoke Terms" },
      "ceterms:statementType": [ "https://some-other-custom-type-of-statement-from-this-publisher" ],
      "ceterms:formattedDescription": {
        "en-us": "In these terms..."
      }
    }
  ]
}

Next, a single StructuredStatement that is reused among many resources, with some additional bells and whistles based on the sorts of things that tend to come up:

{
  "@type": "ceterms:StructuredStatement",
  "@id": "https://.../ce-abc",
  "ceterms:ctid": "ce-abc",
  "ceterms:name": { "en-us": Standards for things from this organization" },
  "ceasn:creator": "https://.../ce-123",
  "ceterms:dateEffective": "2025-01-01",
  "ceterms:expirationDate": "2026-01-01",
  "ceterms:renewalFrequency": "P1Y"
  "ceterms:subjectWebpage": "https://...",
  "ceterms:statementType": [ "statementCat:Standard", "https://some-custom-type" ],
  "ceterms:description": { "en-us": "Simple description for display in search results etc. that don't support formatting" },
  "ceterms:formattedDescription": { "en-us": "Full-featured, formatted, markdown-capable **description**" }
}

{
  "@type": "ceterms:Certificate",
  "ceterms:processStandards": "https://.../ce-abc"
}

{
  "@type": "ceterms:Certificate",
  "ceterms:processStandards": "https://.../ce-abc"
}

{
  "@type": "ceterms:Certificate",
  "ceterms:processStandards": "https://.../ce-abc"
}

[philbarker]

Hi @siuc-nate

Would the Structured Statement's data be largely the same across many records?

I don't think so, not in the registry anyway; we will look for examples where it is but I think these will be exceptions. Outside of the registry maybe (boiler-plate statements get reused, so there may be reuse in an authoring tool).

Would the statement field need to support formatting (e.g. markdown)?

I really hope not. RDF is not my idea of a good standard for conveying formatted text. W3C has some other standard for that, and it makes a lot more sense to me to put RDF into HTML than to put HTML into RDF.

Are there other things that might need to go into the Structured Statement class down the road? It might be better to avoid using up the "ceterms:statement" URI out of the gate in case we need something more specific later.

That's something I'm wondering about too. One approach for modelling Articulation Agreements gives a dozen or more separate properties for each "type" of statement (e.g. purposeStatement, overviewStatement, limitationStatement, mutualObligation...) but the alternative would be to have a single property, which I also pencilled in as statementText and a property in the StructuredStatement to say what role it had, somewhat like we did with QData to avoid a plethora of individual properties one for each thing that could be measured. That alternative comes at a cost too, especially if the StructuredStatement has to be retrieved from somewhere before you know what role it has.

Depending on answers to the above, could the agreement be characterized as a Collection with a list of Structured Statements as members?

No, I don't think that would help. I think that level of abstraction would confuse users and I think it conflates different ways of building things out of different types of "part".

[siuc-nate]

Thanks, Phil.

I don't think so, not in the registry anyway; we will look for examples where it is but I think these will be exceptions. Outside of the registry maybe (boiler-plate statements get reused, so there may be reuse in an authoring tool).

In my second example above, I imagined multiple credentials using the same data for their processStandards property, as that would likely be something written at the organization level (or at least at a level where an organization might reuse it among several credentials at a time, e.g., "all of our ___ degrees follow this set of standards..."). Would it actually be different for each credential? What about transfer value profiles - would each one have its own unique process standards?

I really hope not. RDF is not my idea of a good standard for conveying formatted text. W3C has some other standard for that, and it makes a lot more sense to me to put RDF into HTML than to put HTML into RDF.

Same - but if a statement has any significant complexity to it, I could see that happening. It could be recommended to handle it the way the Finder handles the description field (where line breaks get preserved in the display but it's otherwise rendered as plain text), as that gets you a lot of formatting value for very little effort.

and a property in the StructuredStatement to say what role it had, somewhat like we did with QData to avoid a plethora of individual properties one for each thing that could be measured.

The QData justification/approach/inspiration is where my mind went as well.

No, I don't think that would help. I think that level of abstraction would confuse users and I think it conflates different ways of building things out of different types of "part".

I figured that one was probably a bridge too far, but worth throwing out there nonetheless!

Do we have some robust examples of these statements, along with the context in which they're used (e.g. statements for some related transfer value profiles, statements for some related credentials/credentials from the same organization, statements for an organization itself, statements for other things, etc.)? I think that would go a long way towards answering the above questions. Once we have some good examples, it'll be easier to scope out how much of the statement/its richness/its categorization/its relations to other things/its other metadata (like dates)/etc. really should be (vs can be) put into the CTDL record and how much should just remain on the other end of a link - and from there, it should be easier to figure out the schema for it.

[philbarker]

Do we have some robust examples of these statements....

Yeah, from the prior learning agreements task group, especially Wayne's analysis... are you following that?

[siuc-nate]

I wasn't aware of that task group, I'll go see if I can sign up for it, if I'm not too late.

[philbarker]

First draft proposal:

New property, ceterms:hasStatement to be used when summarizing the content of a document is not sufficient representation of its contents, with a new class ceterms:StructuredStatement for its range.

New property

URI: ceterms:hasStatement
Label: Has Statement
Definition: Indicates contextualized data that reproduces or links to text such as part of a document or information about some aspect of a resource.
Usage note: Do not use if a simple text property such as ceterms:description is adequate. Use statementText to reproduce the text in a document. Use description and subjectWebpage to link to the text in a document, the link should be directly to the relevant section.
Domain: "documents" TBD.
Range: ceterms:StructuredStatement

New Class

URI: ceterms:StructuredStatement
Label: Structured Statement
Definition: Data that reproduces, or links to, a textual statement and provides further contextualizing information.
Usage note: Do not use if a simple text value for a property such as ceterms:description is adequate.

Properties for StructuredStatement

New Properties

URI: ceterms:statementCategory
Label: Statement Category
Definition: Indicates the topic or nature of the statement within the context of the document being represented.
Usage Note: Best practice is to draw from an existing concept scheme such as ceterms:TBD, which may be supplemented by more precise terms from a locally defined concept scheme if required.
Domain: ceterms:StructuredStatement
Range: skos:Concept
target concept scheme To Be Decided.

URI: ceterms:statementText
Definition: Verbatim text of a statement made in a larger document.
Usage note: Use ceterms:description if the data provided is a summary of the content, e.g. when linking to the statement.

Modified Properties
ceterms:name add domain ceterms:StructuredStatement
codedNotation add domain ceterms:StructuredStatement
description add domain ceterms:StructuredStatement
subjectWebpage add domain ceterms:StructuredStatement

Consider for modification
classification add domain ceterms:StructuredStatement
subject add domain ceterms:StructuredStatement

• for both of these we need to avoid confusion over when to use statementCategory, when to use classification and when to use subject.

Examples

1. Agreement purpose
1.1 Facilitating Seamless Transfer & Degree Completion
This agreement provides a structured pathway for students completing the Associate of Applied Science in Advanced Manufacturing Technology at Gateway Technical College to transfer into the Bachelor of Science in Automation Leadership program at the University of Wisconsin-Stout.

1.2 Expanding Access & Supporting Student Mobility
The purpose of this transfer agreement is to establish a cooperative relationship between ITCC and ACE to allow ITCC students completing an associate degree to transition smoothly into an ACE bachelor’s degree program.

To represent this text as data:

{
   "@type": "TransferAgreement",
   "@id": "https://...",
   "hasStatement": [
       {
           "@type": "StructuredStatement",
	   "statementCategory": "statementTypes:purposeStatement",
           "codedNotation": "1.1",
           "name": {
               "en": "Facilitating Seamless Transfer & Degree Completion"
           },
           "statementText": {
               "en": "This agreement provides a structured pathway for students completing the Associate of Applied Science in Advanced Manufacturing Technology at Gateway Technical College to transfer into the Bachelor of Science in Automation Leadership program at the University of Wisconsin-Stout."
           }
       },
       {
           "@type": "StructuredStatement",
	     "statementCategory": "statementTypes:purposeStatement",
           "codedNotation": "1.2",
           "name": {
               "en": "Expanding Access & Supporting Student Mobility"
           },
           "statementText": {
               "en": "The purpose of this transfer agreement is to establish a cooperative relationship between ITCC and ACE to allow ITCC students completing an associate degree to transition smoothly into an ACE bachelor’s degree program."
           }
       }
   ]
}

To link to this text on a webpage:

{
   "@type": "Agreement",
   "@id": "https://...",
   "hasStatement": {
       "@type": "StructuredStatement",
       "statementCategory": "statementTypes:purposeStatement",
       "name": {
           "en": "Purposes of the agreement"
       },
       "description": {
           "en": "The purposes of this agreement are provided under the heading of Facilitating Seamless Transfer & Degree Completion and Expanding Access & Supporting Student Mobility."
       },
       "subjectWebpage": "https://example.edu/transfer-agreements/abc#purposes"
   }
}

[philbarker]

I am currently mulling over whether we should have two properties that may have StructuredStatements as their values:

hasStatement for text that is part of a document being described.
descriptiveStatement for information about some aspect of a resource being described (e.g. learning programs).

[siuc-nate]

Thanks, Phil. That's a lot to think about.

Usage note: Do not use if a simple text property such as ceterms:description is adequate. Use statementText to reproduce the text in a document. Use description and subjectWebpage to link to the text in a document, the link should be directly to the relevant section.

Would this be more useful as a usage note for the class itself, rather than one of the properties that links to it? As a developer looking up the documentation for the class, I'm more likely to see the note if it's on the class directly (plus it means not having to duplicate it for any other property that links to the class).

Usage note: Do not use if a simple text value for a property such as ceterms:description is adequate.

Likewise, I think this would probably work better on the property rather than the class, but I suppose it doesn't hurt.

URI: ceterms:statementCategory
Label: Statement Category

I would suggest ceterms:statementType for the property and ceterms:StatementCategory for the concept scheme, to align with other recent concept scheme additions

URI: ceterms:statementText
Definition: Verbatim text of a statement made in a larger document.
Usage note: Use ceterms:description if the data provided is a summary of the content, e.g. when linking to the statement.

Does this need some mention of how to handle formatted text? Maybe the definition should be something like "verbatim plain-text equivalent of a statement".

Is the "part of a larger document" aspect always true? Maybe "[...], typically made in a larger document"?

codedNotation add domain ceterms:StructuredStatement

Given its usage, would listID work better here? Perhaps both properties? I'm not sure which of the two fits better.

Consider for modification
classification add domain ceterms:StructuredStatement
subject add domain ceterms:StructuredStatement

for both of these we need to avoid confusion over when to use statementCategory, when to use classification and when to use subject.

I think statementType handles the intended usage of classification - is there an example where both are needed?
As for subject, is that getting too far into the weeds of what needs to be captured about a statement? If not, you'd likely (also?) need keywords, date properties, maybe life cycle/version properties, etc. but that feels like a bridge too far (at least for something without its own CTID).

I am currently mulling over whether we should have two properties that may have StructuredStatements as their values:

hasStatement for text that is part of a document being described.
descriptiveStatement for information about some aspect of a resource being described (e.g. learning programs).

If the domain of hasStatement is a TBD class of "document", then a StructuredStatement would itself be "information about some aspect of a [document] being described [including the text itself]", no? Or are you thinking more along the lines of something like this?:

hasStatement -[subPropertyOf]-> hasPart
descriptiveStatement -[subPropertyOf]-> description

On the other hand, properties like "name" or "competencyText" are also simultaneously both "information about" and "part of" a given resource, too. Maybe thinking about the StructuredStatement as being part of a document is technically incorrect (especially if the text loses its formatting), and it really is just descriptive of a statement (even if the text used is more or less identical)?

On the (other) other hand, I can see utility in being able to distinguish (at the level of the property linking to the statement) between a chunk of information that is meant to be interpreted as having directly come from the document vs something that is just a really rich description of some aspect of it, but then, does that step on the toes of the rest of the schema? It offers a similar sort of user-customizable utility as ceterms:classification, but its scope is broad enough that I think it might open the door to putting data into it that would be better suited to other (either existing or "turns out we need this") properties. But maybe you can solve that with a usage note like the one on classification, too.

You could argue that it worked for QData, but I think the flexibility it grants there is core to making QData viable (and thus worth doing); here it's (maybe?) more of a way to capture additional/extra info where the added value might not be worth the complexity.

That's a real brain teaser. I'm not sure where I land on that one at the moment. Maybe some real-world examples will help iron it out?

[philbarker]

@siuc-nate The first few of your comments are the result of me getting stuff switched around and not drafting what I meant to. Thanks for spotting them!
For the comments more or less from "Does this need some mention of how to handle formatted text?" yes, more to think about here. Thanks for your input, I'll use it in the next iteration.

On

hasStatement -[subPropertyOf]-> hasPart
descriptiveStatement -[subPropertyOf]-> description

The first is something I have been thinking about. They are both "conceptually" true, but in RDF terms the second doesn't work. For it to work all values of descriptiveStatement have to be valid values for description but they are not, because they are not Literals of type rdf:langString. The second does work. That is part of my thinking in splitting the two.

[philbarker]

no descriptiveStatement (yet?)

For current Prior Learning Recognition use cases, descriptive statements relate to Courses and Programs. I share @siuc-nate's concern that a general purpose descriptiveStatement property with StructuredStatement values is has a scope that is "broad enough that I think it might open the door to putting data into it that would be better suited to other (either existing or "turns out we need this") properties." Mopre bluntly, it may just be a poor substitute for specific properties we don't yet have but should add. We decided on yesterday's call to put off consideration of how to describe Courses and Programs to a "focus group" after the current Prior Learning Recognition task group. So let's not discuss that further here.

[philbarker]

@siuc-nate

I think statementType handles the intended usage of classification - is there an example where both are needed?

The case in consideration is that Transfer Agreements has Guarantees and Limitations, both which are nice general terms for statementType --> a StatementCategory, but in these go on to make a Guarantee about something or Limitation of something. So something like

    statementType StatementCat:Limitation ;
    subject ["targetNodeDescription"  "Maximum Total Credit"] ;

might be useful. (Now I write it out the use of CredentialAlignmentObject seems like a big negative for subject).

or

    statementType StatementCat:Guarantee ;
    classification someScheme:Housing  ;

Other approaches are plentiful, don't try to list them :-), but I would like to avoid having sub-concepts of Guarantee and Limitation for everything that might be guaranteed or limited, and on their own "Maximum Total Credit" and "Housing" seem more like subject classifications that types of statement. It might even be that name is enough. Still an open issue in my mind.