Skip to content

Commit 9268323

Browse files
sa-bpelakhsa-bpelakh
committed
Merge remote-tracking branch 'origin/release-10.0.0' into develop
2 parents 3b02d4b + 25df791 commit 9268323

13 files changed

+548
-3
lines changed

‎bundle.yaml

+14-1
Original file line numberDiff line numberDiff line change
@@ -163,14 +163,27 @@ actions:
163163
source: "{input}/LICENSE.txt"
164164
target: "{output}"
165165
- action: "copy"
166+
message: "Copying migration queries and scripts."
167+
source: "{input}/migration"
168+
target: "{output}/migration"
169+
- action: "copy"
170+
message: "Copying documentation and patching local links."
166171
source: "{input}/docs"
167172
target: "{output}/Documentation"
173+
replace:
174+
from: "\\(./(\\w+)\\.md\\)"
175+
to: "(./\\g<1>.html)"
168176
includes:
169177
- "ReleaseNotes.md"
178+
- "MajorVersionMigration.md"
170179
- action: "markdown"
171180
message: "Formatting release notes."
172-
source: "{input}/docs/ReleaseNotes.md"
181+
source: "{output}/Documentation/ReleaseNotes.md"
173182
target: "{output}/Documentation/ReleaseNotes.html"
183+
- action: "markdown"
184+
message: "Formatting migration instructions."
185+
source: "{output}/Documentation/MajorVersionMigration.md"
186+
target: "{output}/Documentation/MajorVersionMigration.html"
174187
- action: "move"
175188
message: "Creating Deprecated folder."
176189
source: "{output}"

‎docs/MajorVersionMigration.md

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Major Version Migration
2+
3+
When non-backward compatible changes are introduced into `gist` during major upgrades,
4+
the release package will include queries to facilitate the migration of existing ontologies
5+
and data to conform to the new version of `gist`.
6+
7+
For changes that are not amenable to automatic migration, queries will be provided that
8+
report the use of deleted or modified classes and properties so that mitigation measures
9+
can be initiated.
10+
11+
Every major version of `gist` (starting with 10.0.0) will add a sub-directory under the
12+
`migration` directory containing the queries and two migration scripts:
13+
14+
1. `migrate_local.yaml`, intended to apply changes to locally stored RDF data, and
15+
2. `migrate_endpoint.yaml`, which is used to modify RDF data in a triple store
16+
17+
The migration scripts rely on the [Ontology Toolkit](https://pypi.org/project/onto-tool/), which is a
18+
Python-based open source tool provided by Semantic Arts. It requires Python version 3.8 or greater
19+
to be installed.
20+
21+
## Migrating RDF Data in Local Files
22+
23+
Once you have the Ontology Toolkit installed, issue the following command from the directory where
24+
you cloned [gist](https://github.com/semanticarts/gist):
25+
```shell
26+
onto_tool bundle -v input INPUT-DIR
27+
-v output OUTPUT-DIR
28+
-v report REPORT-DIR migration/v10.0/migrate_local.yaml
29+
```
30+
where _INPUT-DIR_ is the directory in which your RDF data is located, _OUTPUT-DIR_ is the directory where
31+
updated RDF should be written, and REPORT-DIR is a directory where reports regarding any issues found
32+
during migration are stored. The tool will also list the issues during execution. Output and report
33+
directories will be created as needed, but any existing files in them will be overwritten.
34+
35+
Note that only `.ttl` (Turtle) and `.owl` (RDF/XML) files in the _INPUT-DIR_ are transformed - no
36+
subdirectories are traversed, and those would require additional tool invocations.
37+
38+
## Migrating Data in a Triple Store
39+
40+
Once you have the Ontology Toolkit installed, issue the following command from the directory where
41+
you cloned [gist](https://github.com/semanticarts/gist):
42+
```shell
43+
onto_tool bundle -v user USER -v password PWD
44+
-v endpoint ENDPOINT-URI
45+
[ -v update_endpoint UPDATE-URI ]
46+
-v report REPORT-DIR migration/v10.0/migrate_endpoint.yaml
47+
```
48+
where _ENDPOINT-URI_ is the address of your SPARQL endpoint, and _USER_ and _PWD_ are the credentials
49+
required to access it. Only Basic HTTP authentication is handled at this time. If your triple store has
50+
a separate endpoint for UPDATE queries (e.g. Stardog), provide it as _UPDATE-URI_. Reports regarding any
51+
issues found during migration are stored in _REPORT-DIR_. Report directory will be created as needed,
52+
but any existing files in it will be overwritten.

‎docs/ReleaseNotes.md

+6
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,12 @@ gist Release Notes
44
Release 10.0.0
55
-----
66

7+
This is a major release, which includes several changes which break compatibility with previous versions
8+
of `gist`. See the [migration guide](./MajorVersionMigration.md) for documentation on updating existing
9+
`gist`-based ontologies and instance data.
10+
11+
### Major Updates
12+
713
- Renamed 62 object and datatype properties to reflect newly-established conventions. Includes corresponding updates to the [gist style guide](https://github.com/semanticarts/gist/blob/master/docs/gistStyleGuide.md). Issues [188](https://github.com/semanticarts/gist/issues/188), [507](https://github.com/semanticarts/gist/issues/507).
814
- Renamed `MimeType` to `MediaType` to be consistent with [IANA guidelines](https://www.iana.org/assignments/media-types/media-types.xhtml).
915
and [RFC6838](https://tools.ietf.org/html/rfc6838). Issue [#434](<https://github.com/semanticarts/gist/issues/434>).

‎docs/gistStyleGuide.md

+4-2
Original file line numberDiff line numberDiff line change
@@ -101,8 +101,10 @@ Some of the examples resulted in changes to gist `10.0.0`, others are hypothetic
101101
| Alignment with textual definition | `hasBiologicalParent`, not `hasParent`, where the `skos:definition` precludes non-biological relationships |
102102
| Loose coupling of ontology term names | `hasStart`, not `hasStartTimeInstant` |
103103
| Unambiguously indicate directionality | `hasBroader`, not `broader` (as in SKOS) |
104-
| Direction: go up rather than down a tree if a hierarchy exists | `hasParent`, not `hasChild`|||| `hasSuperCategory`, not `hasSubCategory` |
105-
| Word boundaries consisent across ontology rather than following natural language (exception to idiomaticity) | `hasSubTask`,`hasSubCategory`, `hasSuperCategory`, although "subtask" and "subcategory" are words |
104+
| Direction: go up rather than down a tree if a hierarchy exists | `hasParent`, not `hasChild`|
105+
|| `hasSuperCategory`, not `hasSubCategory` |
106+
| Word boundaries consisent across ontology rather than following natural language (exception to idiomaticity) | `hasSubTask`, `hasSubCategory`, `hasSuperCategory`, although "subtask" and "subcategory" are words |
107+
||`hasBirthDate` and `hasDeathDate`, although "birthdate" is a word |
106108

107109
### Instance Local Names
108110

‎migration/v10.0/action_rename_classes.rq

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
prefix gist: <https://ontologies.semanticarts.com/gist/>
2+
3+
DELETE {
4+
graph ?graph {
5+
?ref ?refProp ?oldClass .
6+
?oldClass ?defProp ?defObj .
7+
}
8+
}
9+
INSERT {
10+
graph ?graph {
11+
?ref ?refProp ?newClass .
12+
?newClass ?defProp ?defObj .
13+
}
14+
}
15+
where {
16+
values (?oldClass ?newClass) {
17+
# Issue #434
18+
(gist:MimeType gist:MediaType)
19+
# Issue #483
20+
(gist:BuildingAddress gist:StreetAddress)
21+
}
22+
graph ?graph {
23+
{
24+
?ref ?refProp ?oldClass
25+
} UNION {
26+
?oldClass ?defProp ?defObj
27+
}
28+
}
29+
}

‎migration/v10.0/action_rename_classes_default.rq

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
prefix gist: <https://ontologies.semanticarts.com/gist/>
2+
3+
DELETE {
4+
?ref ?refProp ?oldClass .
5+
?oldClass ?defProp ?defObj .
6+
}
7+
INSERT {
8+
?ref ?refProp ?newClass .
9+
?newClass ?defProp ?defObj .
10+
}
11+
where {
12+
values (?oldClass ?newClass) {
13+
# Issue #434
14+
(gist:MimeType gist:MediaType)
15+
# Issue #483
16+
(gist:BuildingAddress gist:StreetAddress)
17+
}
18+
{
19+
?ref ?refProp ?oldClass
20+
} UNION {
21+
?oldClass ?defProp ?defObj
22+
}
23+
}

‎migration/v10.0/action_rename_properties.rq

+102
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
prefix gist: <https://ontologies.semanticarts.com/gist/>
2+
3+
DELETE {
4+
graph ?graph {
5+
?s ?oldProp ?o .
6+
?ref ?refProp ?oldProp .
7+
?oldProp ?defProp ?defObj .
8+
}
9+
}
10+
INSERT {
11+
graph ?graph {
12+
?s ?newProp ?o .
13+
?ref ?refProp ?newProp .
14+
?newProp ?defProp ?defObj .
15+
}
16+
}
17+
where {
18+
values (?oldProp ?newProp) {
19+
# Issue #171
20+
(gist:decimalValue gist:numericValue)
21+
# Issue #126
22+
(gist:networkConnection gist:links)
23+
(gist:hasFromNode gist:linksFrom)
24+
(gist:hasToNode gist:linksTo)
25+
# Issue #483
26+
(gist:hasStreetAddress gist:hasAddress)
27+
# Issue 188
28+
(gist:directlyPrecedes gist:precedesDirectly)
29+
(gist:hasUoM gist:hasUnitOfMeasure)
30+
(gist:multiplicand gist:hasMultiplicand)
31+
(gist:multiplier gist:hasMultiplier)
32+
(gist:affectedBy gist:isAffectedBy)
33+
(gist:allocatedBy gist:isAllocatedBy)
34+
(gist:denominator gist:hasDenominator)
35+
(gist:numerator gist:hasNumerator)
36+
(gist:categorizedBy gist:isCategorizedBy)
37+
(gist:actualStart gist:hasActualStart)
38+
(gist:actualEnd gist:hasActualEnd)
39+
(gist:expressedIn gist:isExpressedIn)
40+
(gist:plannedStart gist:hasPlannedStart)
41+
(gist:plannedEnd gist:hasPlannedEnd)
42+
(gist:triggeredBy gist:isTriggeredBy)
43+
(gist:hasJurisdiction gist:hasJurisdictionOver)
44+
(gist:governedBy gist:isGovernedBy)
45+
(gist:recognizedBy gist:isRecognizedBy)
46+
(gist:characterizedAs gist:isCharacterizedAs)
47+
(gist:start gist:hasStart)
48+
(gist:end gist:hasEnd)
49+
(gist:fromPlace gist:comesFromPlace)
50+
(gist:toPlace gist:goesToPlace)
51+
(gist:geoContains gist:containsGeographically)
52+
(gist:timeZoneStandardUsed gist:usesTimeZoneStandard)
53+
(gist:identifiedBy gist:isIdentifiedBy)
54+
(gist:permanentGeoOccupies gist:occupiesGeographicallyPermanently)
55+
(gist:offspringOf gist:hasBiologicalParent)
56+
(gist:fromAgent gist:comesFromAgent)
57+
(gist:toAgent gist:goesToAgent)
58+
(gist:memberOf gist:isMemberOf)
59+
(gist:hasGetter gist:hasRecipient)
60+
(gist:directlyPrecededBy gist:followsDirectly)
61+
(gist:offspringOf gist:hasBiologicalParent)
62+
(gist:occursAt gist:occursIn)
63+
(gist:madeUpOf gist:isMadeUpOf)
64+
(gist:convertToBase gist:baseConversionFactor)
65+
(gist:renderedOn gist:isRenderedOn)
66+
(gist:basisFor gist:isBasisFor)
67+
(gist:hasTag gist:tagText)
68+
(gist:connectedTo gist:isConnectedTo)
69+
(gist:about gist:isAbout)
70+
(gist:actual gist:hasActual)
71+
(gist:aspectOf gist:isAspectOf)
72+
(gist:basedOn gist:isBasedOn)
73+
(gist:convertToStandard gist:standardConversionFactor)
74+
(gist:describedIn gist:isDescribedIn)
75+
(gist:directPartOf gist:isDirectPartOf)
76+
(gist:directSubTaskOf gist:isDirectSubtaskOf)
77+
(gist:directlyRecognizedBy gist:isRecognizedDirectlyBy)
78+
(gist:geoContainedIn gist:isGeographicallyContainedIn)
79+
(gist:geoOccupiedBy gist:isGeographicallyOccupiedBy)
80+
(gist:parentOf gist:hasBiologicalOffspring)
81+
(gist:partOf gist:isPartOf)
82+
(gist:planned gist:hasPlanned)
83+
(gist:subTaskOf gist:isSubTaskOf)
84+
(gist:viableRange gist:hasViableRange)
85+
(gist:permanentGeoOccupiedBy gist:isGeographicallyPermanentlyOccupiedBy)
86+
(gist:recordedOn gist:isRecordedAt)
87+
(gist:sameTimeAs gist:isSameTimeAs)
88+
(gist:geoOccupies gist:occupiesGeographically)
89+
(gist:unitSymbolHTML gist:unitSymbolHtml)
90+
(gist:lastModifiedOn gist:wasLastModifiedAt)
91+
(gist:offsetToUniversal gist:hasOffsetToUniversal)
92+
}
93+
graph ?graph {
94+
{
95+
?s ?oldProp ?o
96+
} UNION {
97+
?ref ?refProp ?oldProp
98+
} UNION {
99+
?oldProp ?defProp ?defObj
100+
}
101+
}
102+
}

‎migration/v10.0/action_rename_properties_default.rq

+96
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
prefix gist: <https://ontologies.semanticarts.com/gist/>
2+
3+
DELETE {
4+
?s ?oldProp ?o .
5+
?ref ?refProp ?oldProp .
6+
?oldProp ?defProp ?defObj .
7+
}
8+
INSERT {
9+
?s ?newProp ?o .
10+
?ref ?refProp ?newProp .
11+
?newProp ?defProp ?defObj .
12+
}
13+
where {
14+
values (?oldProp ?newProp) {
15+
# Issue #171
16+
(gist:decimalValue gist:numericValue)
17+
# Issue #126
18+
(gist:networkConnection gist:links)
19+
(gist:hasFromNode gist:linksFrom)
20+
(gist:hasToNode gist:linksTo)
21+
# Issue #483
22+
(gist:hasStreetAddress gist:hasAddress)
23+
# Issue 188
24+
(gist:directlyPrecedes gist:precedesDirectly)
25+
(gist:hasUoM gist:hasUnitOfMeasure)
26+
(gist:multiplicand gist:hasMultiplicand)
27+
(gist:multiplier gist:hasMultiplier)
28+
(gist:affectedBy gist:isAffectedBy)
29+
(gist:allocatedBy gist:isAllocatedBy)
30+
(gist:denominator gist:hasDenominator)
31+
(gist:numerator gist:hasNumerator)
32+
(gist:categorizedBy gist:isCategorizedBy)
33+
(gist:actualStart gist:hasActualStart)
34+
(gist:actualEnd gist:hasActualEnd)
35+
(gist:expressedIn gist:isExpressedIn)
36+
(gist:plannedStart gist:hasPlannedStart)
37+
(gist:plannedEnd gist:hasPlannedEnd)
38+
(gist:triggeredBy gist:isTriggeredBy)
39+
(gist:hasJurisdiction gist:hasJurisdictionOver)
40+
(gist:governedBy gist:isGovernedBy)
41+
(gist:recognizedBy gist:isRecognizedBy)
42+
(gist:characterizedAs gist:isCharacterizedAs)
43+
(gist:start gist:hasStart)
44+
(gist:end gist:hasEnd)
45+
(gist:fromPlace gist:comesFromPlace)
46+
(gist:toPlace gist:goesToPlace)
47+
(gist:geoContains gist:containsGeographically)
48+
(gist:timeZoneStandardUsed gist:usesTimeZoneStandard)
49+
(gist:identifiedBy gist:isIdentifiedBy)
50+
(gist:permanentGeoOccupies gist:occupiesGeographicallyPermanently)
51+
(gist:offspringOf gist:hasBiologicalParent)
52+
(gist:fromAgent gist:comesFromAgent)
53+
(gist:toAgent gist:goesToAgent)
54+
(gist:memberOf gist:isMemberOf)
55+
(gist:hasGetter gist:hasRecipient)
56+
(gist:directlyPrecededBy gist:followsDirectly)
57+
(gist:offspringOf gist:hasBiologicalParent)
58+
(gist:occursAt gist:occursIn)
59+
(gist:madeUpOf gist:isMadeUpOf)
60+
(gist:convertToBase gist:baseConversionFactor)
61+
(gist:renderedOn gist:isRenderedOn)
62+
(gist:basisFor gist:isBasisFor)
63+
(gist:hasTag gist:tagText)
64+
(gist:connectedTo gist:isConnectedTo)
65+
(gist:about gist:isAbout)
66+
(gist:actual gist:hasActual)
67+
(gist:aspectOf gist:isAspectOf)
68+
(gist:basedOn gist:isBasedOn)
69+
(gist:convertToStandard gist:standardConversionFactor)
70+
(gist:describedIn gist:isDescribedIn)
71+
(gist:directPartOf gist:isDirectPartOf)
72+
(gist:directSubTaskOf gist:isDirectSubtaskOf)
73+
(gist:directlyRecognizedBy gist:isRecognizedDirectlyBy)
74+
(gist:geoContainedIn gist:isGeographicallyContainedIn)
75+
(gist:geoOccupiedBy gist:isGeographicallyOccupiedBy)
76+
(gist:parentOf gist:hasBiologicalOffspring)
77+
(gist:partOf gist:isPartOf)
78+
(gist:planned gist:hasPlanned)
79+
(gist:subTaskOf gist:isSubTaskOf)
80+
(gist:viableRange gist:hasViableRange)
81+
(gist:permanentGeoOccupiedBy gist:isGeographicallyPermanentlyOccupiedBy)
82+
(gist:recordedOn gist:isRecordedAt)
83+
(gist:sameTimeAs gist:isSameTimeAs)
84+
(gist:geoOccupies gist:occupiesGeographically)
85+
(gist:unitSymbolHTML gist:unitSymbolHtml)
86+
(gist:lastModifiedOn gist:wasLastModifiedAt)
87+
(gist:offsetToUniversal gist:hasOffsetToUniversal)
88+
}
89+
{
90+
?s ?oldProp ?o
91+
} UNION {
92+
?ref ?refProp ?oldProp
93+
} UNION {
94+
?oldProp ?defProp ?defObj
95+
}
96+
}

‎migration/v10.0/detect_new_domain_restrictions.rq

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
prefix skos: <http://www.w3.org/2004/02/skos/core#>
2+
prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>
3+
prefix sh: <http://www.w3.org/ns/shacl#>
4+
PREFIX owl: <http://www.w3.org/2002/07/owl#>
5+
prefix gist: <https://ontologies.semanticarts.com/gist/>
6+
prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
7+
8+
# validate domain (Person U Organization) on hasCommunicationAddress
9+
CONSTRUCT {
10+
?report a sh:ValidationReport ;
11+
sh:conforms false ;
12+
sh:result
13+
[
14+
a sh:ValidationResult ;
15+
sh:focusNode ?failedEntity ;
16+
sh:resultMessage "Domain restriction on gist:hasCommunicationAddress violated.";
17+
sh:resultSeverity sh:Warning ;
18+
sh:sourceConstraintComponent <urn:constraint:hasCommunicationAddress-domain>
19+
] .
20+
}
21+
WHERE {
22+
graph ?g1 { ?failedEntity gist:hasCommunicationAddress ?addr . }
23+
FILTER NOT EXISTS {
24+
{ ?failedEntity a gist:Person } UNION { ?failedEntity a gist:Organization }
25+
}
26+
27+
bind(<urn:new-domain-validation-report> as ?report)
28+
}

0 commit comments

Comments
 (0)