Managing documention of term change #238
In the Namespace Policy, it says that documentation of changes to a terms (class, property, concept) will be accessible from the terms schema/scheme declarations. I propose that we include in our schema declarations the namespace prefix used by the Library of Congress of terms needed for this purpose. See "cs" in the prefix of the code example below the image containing an example.
The image is set of two example changes using our property, jobsObtained. Our term declarations would include the property skos:changeNote for pointing to external instances of cs:ChangeSet in a http://purl.org/ctdl/history/ namespace.
Here is a N3 (turtle)
@prefix ceterms: <http://purl.org/ctdl/terms/> .
@prefix history: <http://purl.org/ctdl/history/> .
@prefix cs: <http://purl.org/vocab/changeset/schema#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix xml: <http://www.w3.org/XML/1998/namespace> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
# jobsObtained PROPERTY HAS TWO CHANGES
ceterms:jobsObtained a rdfs:Property ;
skos:changeNote <http://purl.org/ctdl/history/jobsObtained2>, <http://purl.org/ctdl/history/jobsObtained1>.
# CHANGE TWO
history:jobsObtained2 a cs:ChangeSet ;
cs:changeReason "Clarified definitions use of ..."^^xsd:string ;
cs:createdDate "2017-01-05T14:16:06"^^xsd:dateTime ;
cs:creatorName "Jeanne Kitchens" ;
cs:precedingChangeSet history:jobsObtained1 ;
cs:subjectOfChange ceterms:jobsObtained .
# CHANGE ONE
history:jobsObtained1 a cs:ChangeSet ;
cs:changeReason "Updated definition to express ..."^^xsd:string ;
cs:createdDate "2016-11-17T00:00:00"^^xsd:dateTime ;
cs:creatorName "Stuart Sutton" ;
cs:subjectOfChange ceterms:jobsObtained .
The following if JSONLD generated using http://rdf-translator.appspot.com/ and the above turtle code:
{
"@context": {
"ceterms": "http://purl.org/ctdl/terms/",
"cs": "http://purl.org/vocab/changeset/schema#",
"history": "http://purl.org/ctdl/history/",
"rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
"rdfs": "http://www.w3.org/2000/01/rdf-schema#",
"skos": "http://www.w3.org/2004/02/skos/core#",
"xsd": "http://www.w3.org/2001/XMLSchema#"
},
"@graph": [
{
"@id": "ceterms:jobsObtained",
"@type": "rdfs:Property",
"skos:changeNote": [
{
"@id": "history:jobsObtained2"
},
{
"@id": "history:jobsObtained1"
}
]
},
{
"@id": "history:jobsObtained2",
"@type": "cs:ChangeSet",
"cs:changeReason": "Clarified definitions use of ...",
"cs:createdDate": {
"@type": "xsd:dateTime",
"@value": "2017-01-05T14:16:06"
},
"cs:creatorName": "Jeanne Kitchens",
"cs:precedingChangeSet": {
"@id": "history:jobsObtained1"
},
"cs:subjectOfChange": {
"@id": "ceterms:jobsObtained"
}
},
{
"@id": "history:jobsObtained1",
"@type": "cs:ChangeSet",
"cs:changeReason": "Updated definition to express ...",
"cs:createdDate": {
"@type": "xsd:dateTime",
"@value": "2016-11-17T00:00:00"
},
"cs:creatorName": "Stuart Sutton",
"cs:subjectOfChange": {
"@id": "ceterms:jobsObtained"
}
}
]
}
An instance of a cs:ChangeSet can be very specific in describing the 'delta' of a change through use of two additional properties: cs:addition and cs:removal--each pertaining to a specific triple in the definition of a term. Thus, you can express:
ADDITION: cs:addition DELETION: cs:deletion CHANGE: cs:deletion + cs:addition
Below I have expanded the turtle encoding of the example above. Note that it uses a new entity called cs:Statement which is equal to "triple" and then uses of rdf:subject, rdf:predicate, and rdf:object to express the components of that triple (cs:Statement):
@prefix ceterms: <http://purl.org/ctdl/terms/> .
@prefix history: <http://purl.org/ctdl/history/> .
@prefix cs: <http://purl.org/vocab/changeset/schema#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix xml: <http://www.w3.org/XML/1998/namespace> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
# jobsObtained PROPERTY HAS TWO CHANGES
ceterms:jobsObtained a rdfs:Property ;
skos:changeNote <http://purl.org/ctdl/history/jobsObtained2>, <http://purl.org/ctdl/history/jobsObtained1>.
#==================================
# CHANGE TWO
history:jobsObtained2 a cs:ChangeSet ;
cs:changeReason "Clarified definitions use of ..."^^xsd:string ;
cs:removal history:50b19fd2-f97a-499e-8fc4-c34778168dc8 ;
cs:addition history:516bf337-e8e2-4b93-9127-f0e65fa3ff9f ;
cs:createdDate "2017-01-05T14:16:06"^^xsd:dateTime ;
cs:creatorName "Jeanne Kitchens" ;
cs:precedingChangeSet history:jobsObtained1 ;
cs:subjectOfChange ceterms:jobsObtained .
# CHANGE ONE
history:jobsObtained1 a cs:ChangeSet ;
cs:changeReason "Updated definition to express ..."^^xsd:string ;
cs:removal history:da7a35e9-889b-4a3a-8a93-d10ef6894486 ;
cs:addition history:0ef25f57-f394-443e-886f-0081a0d37099 ;
cs:createdDate "2016-11-17T00:00:00"^^xsd:dateTime ;
cs:creatorName "Stuart Sutton" ;
cs:subjectOfChange ceterms:jobsObtained .
#==================================
# DELTA CHANGE ONE
# Removal
history:da7a35e9-889b-4a3a-8a93-d10ef6894486 a cs:Statement ;
rdf:subject ceterms:jobsObtained ;
rdf:predicate rdfs:comment ;
rdf:object "The number of jobs obtained."@en-US .
# Addition
history:0ef25f57-f394-443e-886f-0081a0d37099 a cs:Statement ;
rdf:subject ceterms:jobsObtained ;
rdf:predicate rdfs:comment ;
rdf:object "The number of jobs obtained in the region."@en-US.
# DELTA CHANGE TWO
# Removal
history:50b19fd2-f97a-499e-8fc4-c34778168dc8 a cs:Statement ;
rdf:subject ceterms:jobsObtained ;
rdf:predicate rdfs:comment ;
rdf:object "The number of jobs obtained in the region."@en-US.
# Addition
history:516bf337-e8e2-4b93-9127-f0e65fa3ff9f a cs:Statement ;
rdf:subject ceterms:jobsObtained ;
rdf:predicate rdfs:comment ;
rdf:object "The number of jobs obtained in the region during a given timeframe."@en-US.
Below is a graph illustrating the immediately preceding code demonstrating the "delta" of both changes using the cs:removal and cs:addition properties with the cs:Statement entity describing the individual, changed triples in the terms description being revised (click image to enlarge).
Update on this issue (see also second half of #319).
The discussion above treats linking a term definition to its history through 1-n instances of skos:changeNote defining the term's relationship to 1-n instances of cs:ChangeSet . The difference below creates a new entity ( meta:ChangeHistory ) and the use of a single skos:changeNote property per term pointing to this new class where an index of 1-n changes is maintained. In the image below, the change from the top of this issue is illustrated through the addition of the yellow (history) node:
managing_change-2
Here's an example in RDF/Turtle:
@prefix ceterms: <http://purl.org/ctdl/terms/> .
@prefix cs: <http://purl.org/vocab/changeset/schema#> .
@prefix history: <http://purl.org/ctdl/history/> .
@prefix meta: <http://purl.org/ctdl/meta/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix schema: <http://schema.org/> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix vs: <http://www.w3.org/2003/06/sw-vocab-status/ns#> .
@prefix xml: <http://www.w3.org/XML/1998/namespace#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
ceterms:credentialingAction a rdf:Property ;
rdfs:label "Credentialing Action"@en-US ;
rdfs:comment "Indicates an past or potential credentialing action in which the agent being described plays an 'object' role."@en-US ;
vs:term_status "vs:stable"@en-US ;
schema:domainIncludes ceterms:CredentialOrganization, ceterms:QACredentialOrganization, ceterms:CredentialPerson ;
schema:rangeIncludes ceterms:AccreditAction, ceterms:AdvancedStandingAction, ceterms:ApproveAction,
ceterms:CredentialAction, ceterms:OdderAction, ceterms:RecognizeAction, ceterms:RegulateAction,
ceterms:RenewAction, ceterms:RevokeAction, ceterms:RightsAction ;
skos:changeNote history:credenialingAction .
# CHANGE HISTORY
history:credentialingAction a meta:ChangeHistory ;
meta:hasChangeSet history:credentialingAction-1 ;
meta:hasChangeSet history:credentialingAction-2 .
#----------------------------
# CHANGE SET (credentialingAction-1)
history:credentialingAction-1 a cs:ChangeSet ;
cs:changeReason "Clarify that the definition of the credentialingAction property includes actions already taken as well as potential actions."^^xsd:string;
cs:removal history:da7a35e9-889b-4a3a-8a93-d10ef6894486 ;
cs:addition history:0ef25f57-f394-443e-886f-0081a0d37099 ;
cs:createdDate "2017-02-11"^^xsd:date ;
cs:creatorName "CTDL Team" ;
cs:subjectOfChange ceterms:credentialingAction .
# REMOVE TRIPLE
history:da7a35e9-889b-4a3a-8a93-d10ef6894486 a cs:Statement ;
rdf:subject ceterms:credentialingAction ;
rdf:predicate rdfs:comment ;
rdf:object "Indicates a potential credentialing action, which describes an idealized action in which this thing would play an 'object' role."@en-US .
# ADD TRIPLE
history:0ef25f57-f394-443e-886f-0081a0d37099 a cs:Statement ;
rdf:subject ceterms:credentialingAction ;
rdf:predicate rdfs:comment ;
rdf:object "Indicates a past or potential credentialing action in which the agent being described plays an 'object' role."@en-US.
#----------------------------
# CHANGE SET (credentialingAction-2)
history:credentialingAction-2 a cs:ChangeSet ;
cs:changeReason "Remove statement that credentialingAction is a subproperty of schema:potentialAction because the schema.org term is too narrow."^^xsd:string;
cs:removal history:7282ebb2-b45a-4ea5-b5b8-da72d665bbcc ;
cs:createdDate "2017-02-11"^^xsd:date ;
cs:creatorName "CTDL Team" ;
cs:precedingChangeSet history:credentialingAction-1;
cs:subjectOfChange ceterms:credentialingAction .
# REMOVE TRIPLE
history:7282ebb2-b45a-4ea5-b5b8-da72d665bbcc a cs:Statement ;
rdf:subject ceterms:credentialingAction ;
rdf:predicate rdfs:subPropertyOf ;
rdf:object schema:potentialAction .