Merge 10.0.0 from develop

Author: sa-bpelakh

.github/workflows/validate.yaml

@@ -0,0 +1,22 @@
+name: Validate gist Ontology
+
+on: [push]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+      - name: Install onto-tool
+        run: |
+          python -m pip install --upgrade pip
+          pip install onto-tool
+      - name: Build distribution
+        run: |
+          onto_tool bundle bundle.yaml

bundle.yaml

@@ -63,9 +63,23 @@ actions:
   source: "{input}"
   includes:
     - gistCore.ttl
+    - gistMediaTypes.ttl
     - gistValidationAnnotations.ttl
   shapes:
     source: "{input}/ontologyShapes.ttl"
+- action: "verify"
+  message: "Verify ontology via queries."
+  type: "construct"
+  inference: "none"
+  source: "{input}"
+  includes:
+    - gistCore.ttl
+  stopOnFail: false
+  target: '{input}/validation'
+  queries:
+    source: '{input}/validation_queries'
+    includes:
+      - '*_construct.rq'
 - action: "mkdir"
   directory: "{output}"
 - action: "copy"
@@ -80,6 +94,7 @@ actions:
     to: "\\g<1>{version}.ttl"
   includes:
     - gistCore.ttl
+    - gistMediaTypes.ttl
     - gistDeprecated.ttl
 - action: "definedBy"
   message: "Adding rdfs:definedBy."
@@ -148,14 +163,27 @@ actions:
   source: "{input}/LICENSE.txt"
   target: "{output}"
 - action: "copy"
+  message: "Copying migration queries and scripts."
+  source: "{input}/migration"
+  target: "{output}/migration"
+- action: "copy"
+  message: "Copying documentation and patching local links."
   source: "{input}/docs"
   target: "{output}/Documentation"
+  replace:
+    from: "\\(./(\\w+)\\.md\\)"
+    to: "(./\\g<1>.html)"
   includes:
     - "ReleaseNotes.md"
+    - "MajorVersionMigration.md"
 - action: "markdown"
   message: "Formatting release notes."
-  source: "{input}/docs/ReleaseNotes.md"
+  source: "{output}/Documentation/ReleaseNotes.md"
   target: "{output}/Documentation/ReleaseNotes.html"
+- action: "markdown"
+  message: "Formatting migration instructions."
+  source: "{output}/Documentation/MajorVersionMigration.md"
+  target: "{output}/Documentation/MajorVersionMigration.html"
 - action: "move"
   message: "Creating Deprecated folder."
   source: "{output}"

docs/ChangeAndReleaseManagement.md

@@ -28,22 +28,30 @@ Workflow: Implementation, Pull Requests, and Merges
 Versions and Version Numbering
 -----
 
-Version numbers are of the form X.x.x (major.minor.patch). We follow [Semantic Versioning 2.0.0](https://semver.org/): as a guideline, but adjust as needed.
+Version numbers are of the form `X.x.x` (major.minor.patch). We follow [Semantic Versioning 2.0.0](https://semver.org/): as a guideline, but adjust as needed.
 
 - **Major:** Non-backward-compatible (i.e., reasoning produces different results).
   - Examples: adding a restriction, domain, range.
+  - Major changes should have a significant impact aside from technically modifying inferencing, if the latter is low-impact. For example, changing an equivalent class assertion pointing to a union class to a subclass axiom in order to allow new subclasses to be defined is not a major change.
 
-- **Minor:** New, backward-compatible functionality. May constitute a large change to the ontology, such as addition of a new module.
-  - Examples: adding a class or property; removing a restriction.
+- **Minor:** New, backward-compatible functionality. Includes _any_ addition to the ontology, even annotation properties. May constitute a large change to the ontology, such as addition of a new module.
+  - Examples: adding a class or property; removing a restriction; adding annotation property `domainIncludes`; deprecation of a term (see following section Deprecation and Deletion Policy).
 
-- **Patch:** No new functionality except for bug fixes.
-  - Examples: Fixing a typo in an annotation, changing a property that was incorrectly defined as inverse functional rather than functional.
-
-Additional notes:
+- **Patch:** No new functionality other than bug fixes.
+  - Correction of an error, even if not backward-compatible, does not require a major release. The expectation is that users will not have implemented against an obvious error. This would be a patch.
+  - Examples: Fixing a typo in an annotation; changing a property that was incorrectly defined as inverse functional rather than functional.
+  
+Deprecation and Deletion Policy
+-----
 
-- Correction of an error, even if not backward-compatible, does not require a major release. The expectation is that users will not have implemented against an obvious error. This would be a patch.
-- When a local name is altered, the original term is deprecated to make it a minor rather than major change. The deprecated term receives an `owl:equivalentClass` or `owl:equivalentProperty` assertion to the new term. Deprecated terms may be removed in a future major release. Deprecated terms reside in the `gistDeprecated.ttl` file. If a user wants to use a deprecated term, he/she should import this file into his/her ontology, which in turn imports `gistCore.ttl` and thus all of gist.
-- Major changes should have a significant impact aside from technically modifying inferencing if this is low-impact. E.g., when an equivalent class axiom to a union class is changed to a subclass axiom in order to allow new subclasses to be defined.
+- Terms to be removed, including changing a local name (which constitutes a removal plus an addition), enter a deprecation-deletion cycle.
+- Deletion is a major change. If the next release is not a major release, terms must be deprecated rather than deleted.
+- Deprecation is a minor change, since the deprecated term is still available for use. A patch release may not contain deprecations.
+- Existing use of deprecated terms can be maintained, but users should not create new references to these terms. Rather, they should future-proof by using the new term, if there is one.
+- Exception to deprecation: if the original term is referenced by other term definitions, as in a domain or range axiom, such that a change to that reference constitutes a major change, the term cannot be deprecated in a minor release. The change or removal must wait until the next major release, when the references to it can also be modified or removed.
+- A deprecated term receives an `owl:deprecated` true assertion, and an `owl:equivalentClass` or `owl:equivalentProperty` assertion pointing to the new term.
+- Deprecated terms are moved to the `gistDeprecated.ttl` file. To use a deprecated term, this file should be imported into the ontology. The deprecation file imports the rest of gist.
+- A major release contains no deprecations. That is, all currently deprecated terms are deleted, and any other terms will be directly deleted rather than deprecated first.
 
 Releases
 -----

docs/MajorVersionMigration.md

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

docs/ReleaseNotes.md

@@ -1,6 +1,56 @@
 gist Release Notes
 =====
 
+Release 10.0.0
+-----
+
+This is a major release, which includes several changes which break compatibility with previous versions
+of `gist`. See the [migration guide](./MajorVersionMigration.md) for documentation on updating existing
+`gist`-based ontologies and instance data.
+
+### Major Updates
+
+- 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).
+- Renamed `MimeType` to `MediaType` to be consistent with [IANA guidelines](https://www.iana.org/assignments/media-types/media-types.xhtml).
+  and [RFC6838](https://tools.ietf.org/html/rfc6838). Issue [#434](<https://github.com/semanticarts/gist/issues/434>).
+- Renamed `gist:decimalValue` to `gist:numericValue` and expanded property range to include all numeric data types.
+  supported by OWL.  Issue [#171](<https://github.com/semanticarts/gist/issues/171>).
+- Refactored ordered collection model. Issues [#112](<https://github.com/semanticarts/gist/issues/112>), [#540](<https://github.com/semanticarts/gist/issues/540>).
+    - Added predicate `gist:providesOrderFor`.
+    - Deleted classes `gist:OrdinalCollection` and `gist:OrdinalMember`.
+- Changes to and affecting `gist:Person`, as per issue [#136](https://github.com/semanticarts/gist/issues/136):
+    - Removed `owl:someValuesFrom gist:name` restriction from `gist:Person`.
+    - Made `gist:hasBirthDate` a subproperty of `gist:hasStart` rather than `gist:hasActualStart`.
+- Refactored the way network connections are modeled per issue [#126](<https://github.com/semanticarts/gist/issues/126>):
+    - `networkConnection`, `hasFromNode` and `hasToNode` have been renamed to `links`, `linksFrom` and `linksTo`, respectively.
+    - Added a restriction on `NetworkLink` that it must have exactly 2 links.
+    - Added restrictions on `NetworkLink` and `NetworkNode` that they must be `isMemberOf` a `Network`.
+- Extended the range of `comesFromPlace`/`goesToPlace` to include `gist:Address` in addition to `gist:Place`.
+  Issue [#392](<https://github.com/semanticarts/gist/issues/392>).
+- Modified classes and properties related to street addresses as per issue [#483](<https://github.com/semanticarts/gist/issues/483>):
+    - Removed `BuildingAddress`.
+    - Added `StreetAddress` as subclass of `PostalAddress`.
+    - Replaced `hasStreetAddress` with the more general `hasAddress`. Removed `streetAddressOf`.
+    - Removed `communicationAddressOf` in a general effort to trim unused inverse properties.
+    - Clarified the definition of `hasCommunicationAddress` (now a subproperty of `hasAddress`),
+      added domain (`Person U Organization`).
+
+### Minor Updates
+
+- Added annotation properties which provide usage guidance for properties without the constraints imposed by `rdfs:range` and `rdfs:domain`: Issue [#389](https://github.com/semanticarts/gist/issues/389).
+    - `domainIncludes`
+    - `rangeIncludes`
+- Created a `gistMediaTypes` ontology to declare `MediaType` instances relevant to semantic applications.
+  Issue [#463](<https://github.com/semanticarts/gist/issues/463>).
+
+### Patch Updates
+
+- Updated annotations for `isBasedOn` and `isBasisFor` properties. Issue [#139](https://github.com/semanticarts/gist/issues/139)
+- `hasDirectSubCategory` is now a subproperty of `hasSubCategory`, as it was always supposed to be.  Issue [#481](https://github.com/semanticarts/gist/issues/481).
+- Clarified the definition of `ContemporaneousEvent`. Issue [#174](<https://github.com/semanticarts/gist/issues/174>).
+
+Import URL: <https://ontologies.semanticarts.com/o/gistCore10.0.0>.
+
 Release 9.7.0
 -----
 
@@ -11,7 +61,7 @@ Release 9.7.0
 ### Patch Updates
 
 - Updated annotations for the following properties regarding the hasDirectX/hasX pattern. Issue [#115](https://github.com/semanticarts/gist/issues/115)
-    - `geoContains`, `geoContainedIn` 
+    - `geoContains`, `geoContainedIn`
     - `directPartOf`,`hasDirectPart`
     - `directlyPrecededBy`, `directlyPrecedes`
 - Declare `gist:identifies` as `owl:FunctionalProperty` rather than `owl:InverseFunctionalProperty` (bug fix). Issue [#180](https://github.com/semanticarts/gist/issues/180).
@@ -27,11 +77,11 @@ Release 9.6.0
 - Refactored `hasParty`, `giver` and `getter`. Issue [#133](https://github.com/semanticarts/gist/issues/133).
     - `giver` and `getter`
         - Renamed to `hasGiver` and `hasGetter`
-        - The newly named versions are no longer subproperties of `hasParty`
+        - The newly named versions are no longer sub-properties of `hasParty`
         - Deprecated `giver` and `getter`
     - New property: `hasParticipant`
         - No domain or range
-        - Has subproperties: `hasGiver`, `hasGetter`, `hasParty`, `fromAgent` and `toAgent`
+        - Has sub-properties: `hasGiver`, `hasGetter`, `hasParty`, `fromAgent` and `toAgent`
     - Added a `skos:scopeNote` to `fromAgent`
     - Added a `skos:example` to `hasParty`
     - Updated `skos:definition`s for `toAgent` and `fromAgent`
@@ -75,7 +125,7 @@ Release 9.4.0
 ### Minor Updates
 
 - Replaced the union class equivalences in the definitions of `gist:Artifact` and `gist:Place` with subclass assertions from each of the union class members. Issues [#110](https://github.com/semanticarts/gist/issues/110), [#343](https://github.com/semanticarts/gist/issues/343).
-- Made changes to `Category` predicates: added intransitive properties `gist:hasDirectSubCategory` and `gist:hasDirectSuperCategory` as subproperties of `gist:hasSubCategory` and `gist:hasSuperCategory`, respectively, and made the latter transitive. Issues [#104](https://github.com/semanticarts/gist/issues/104), [#107](https://github.com/semanticarts/gist/issues/107).
+- Made changes to `Category` predicates: added intransitive properties `gist:hasDirectSubCategory` and `gist:hasDirectSuperCategory` as sub-properties of `gist:hasSubCategory` and `gist:hasSuperCategory`, respectively, and made the latter transitive. Issues [#104](https://github.com/semanticarts/gist/issues/104), [#107](https://github.com/semanticarts/gist/issues/107).
 - Replaced `gist:Weight` with `gist:Mass` in all contexts. Issue [#105](https://github.com/semanticarts/gist/issues/105).
 
 ### Patch Updates
@@ -134,7 +184,7 @@ Release 9.0
 
 ### Miscellaneous
 
-- The `gist` namespace has been modfied from `http:` to `https:`.
+- The `gist` namespace has been modified from `http:` to `https:`.
 - Added comments to ontologies.
 - Added labels and comments to many properties and classes.
 - `SocialBeing` has been removed.
@@ -257,7 +307,7 @@ Release 7.3
 - removal of redundant imports and redundant classes already defined in another ontology
 - relaxed the domain on gist:start and gist:end
 - expanded the range of gist:fromAgent and gist:toAgent
-- added to the Units of Measure ontology and corrected an erronoeously named class
+- added to the Units of Measure ontology and corrected an erroneously named class
 
 See ChangeLog in pdf file for full details of changes.
 
@@ -291,7 +341,7 @@ Primarily fixes minor errors like typos in our gist 7.0 release.
 
 Below is a brief summary of the changes that have semantic import from an inference perspective (axiom added, removed, changed, etc.) or that are backward incompatible.
 
-- Made `gist:uniqueText` a sub-property of `gist:containedText`.
+- Made `gist:uniqueText` a subproperty of `gist:containedText`.
 - Added `gist:Agreement` to range of `gist:governs`.
 - Changed `gist:prevent`, `gist:allow` and `gist:require` to `gist:prevents`, `gist:allows`, and `gist:requires`.
 - Changed restriction on `gist:Offer` to use `gist:hasDirectPart some gist:CatalogItem`.