Merge pull request #418 from semanticarts/develop

Merge 9.5.0 release from develop to master

bundle.yaml

@@ -94,9 +94,41 @@ actions:
   target: "{output}"
   rename:
     from: "(.*)\\.ttl"
-    to: "\\g<1>.json"
+    to: "\\g<1>.jsonld"
   includes:
     - "*.ttl"
+- action: "sparql"
+  source: "{output}"
+  target: "{output}/rdfsAnnotations.ttl"
+  format: "turtle"
+  includes:
+    - "*.ttl"
+  query: >
+    prefix gist: <https://ontologies.semanticarts.com/gist/>
+    prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>
+    prefix skos: <http://www.w3.org/2004/02/skos/core#>
+    CONSTRUCT {{
+      ?entity rdfs:label ?label ;
+              rdfs:comment ?comment .
+    }}
+    WHERE {{
+      {{ ?entity skos:prefLabel ?label }}
+      UNION
+      {{
+        VALUES (?prop ?prefix ) {{
+          ( skos:altLabel "ALT: " )
+          ( skos:definition "DEFINITION: " )
+          ( skos:example "EXAMPLE: " )
+          ( skos:scopeNote "NOTE: " )
+        }}
+        ?entity ?prop ?text .
+        BIND(CONCAT(?prefix, ?text) as ?comment)
+      }}
+    }}
+- action: "transform"
+  tool: "serializer"
+  source: "{output}/rdfsAnnotations.ttl"
+  target: "{output}/rdfsAnnotations.ttl"
 - action: "copy"
   source: "{input}/LICENSE.txt"
   target: "{output}"
@@ -114,4 +146,4 @@ actions:
   includes:
     - "*Deprecated*.ttl"
     - "*Deprecated*.rdf"
-    - "*Deprecated*.json"
+    - "*Deprecated*.jsonld"

docs/ReleaseNotes.md

@@ -1,65 +1,43 @@
 gist Release Notes
 =====
 
-Release 9.4.0
+Release 9.5.0
 -----
 
 ### Minor Updates
 
-*Removed equivalences to union classes from the definitions of `gist:Artifact` and `gist:Place`*
-
-- Description: Replaced the union class equivalence assertions from `gist:Artifact` and `gist:Place` with `rdfs:subClassOf` assertions from each of the union class members to `gist:Artifact` or `gist:Place`, as appropriate.
-- Rationale: Stating equivalence of a class to a union class prevents adding a new subclass which is not also a subclass of one of the union class members, thus reducing extensibility of the ontology.
-- Impact: Removes the inference that an instance of `gist:Artifact` or `gist:Place` is also an instance of one of the members of the union class. Presumably low impact since this is a weak inference.
-- Issues: [#110](https://github.com/semanticarts/gist/issues/110), [#343](https://github.com/semanticarts/gist/issues/343).
-
-*Changes to Category predicates*
-
-- Description: Added intransitive properties `gist:hasDirectSubCategory` and `gist:hasDirectSuperCategory` as subproperties of `gist:hasSubCategory` and `gist:hasSuperCategory`, respectively. The latter are now defined as transitive.
-- Rationale: The direct sub/supercategory properties provide a mechanism for defining gapless taxonomy trees. The existing properties are logically transitive.
-- Impact: No changes required to existing implementations. The changes enhance the definition of taxonomy trees.
-- 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*
-
-- Description: Deprecated `gist:Weight`; `gist:Mass` should be used instead. All axiomatic references to `gist:Weight` have been changed to `gist:Mass`.
-- Rationale: Standardize to `gist:Mass` rather than mixing `gist:Mass` and `gist:Weight`.
-- Impact: Users can continue to use the `gist:Weight` class by importing `gistDeprecated`, but it will be removed in a future major release. New implementations should use `gist:Mass`.
-- Issue: [#105](https://github.com/semanticarts/gist/issues/105).
+- Converted RDFS annotations to SKOS annotations. See [gist style guide](gistStyleGuide.md) for usage details. A file containing legacy RDFS annotations is included in the release package for those who wish to continue using them for existing terms. Issues [#351](https://github.com/semanticarts/gist/issues/351), [#379](https://github.com/semanticarts/gist/issues/379).
+- Deprecated `gist:geoDirectlyContains` and `gist:geoDirectlyContainedIn`. Issue [#328](https://github.com/semanticarts/gist/issues/328).
+- Removed `gist:Address` from range of `gist:toAgent` and `gist:fromAgent`. Issue [#391](https://github.com/semanticarts/gist/issues/391).
 
 ### Patch Updates
 
-*Made `gist:hasPhysicalLocation` transitive*
-
-- Description: `gist:hasPhysicalLocation` was erroneously not defined as transitive.
-- Rationale: Logically, physical location is a transitive (containment) relationship.
-- Issues: [#109](https://github.com/semanticarts/gist/issues/109).
+- Modified build to create JSON-LD ontology files with `.jsonld` extension. Issue [#365](https://github.com/semanticarts/gist/issues/365).
+- Documentation:
+  - Documented policy change on submission of PRs by external contributors (PRs from external contributors are now accepted for review if submitted with an issue). Issue [#382](https://github.com/semanticarts/gist/issues/382).
+  - Documented new, condensed release notes format (reverted release note format introduced in 9.4.0). Issue [#401](https://github.com/semanticarts/gist/issues/401).
+- Added a standard `pre-commit` hook which applies uniform formatting to RDF files using `tools/rdf-toolkit.jar`. Issue [#228](https://github.com/semanticarts/gist/issues/228).
+- Conformed definition of `gist:_second` to other `gist:BaseUnit` individuals. Issue [#92](https://github.com/semanticarts/gist/issues/92).
+- Fixed label of TaskTemplate. Issue [#407](https://github.com/semanticarts/gist/issues/407).
 
-*Deprecated `gist:_unitedNations`*
+Import URL: <https://ontologies.semanticarts.com/o/gistCore9.5.0>.
 
-- Description: Deprecated `gist:_unitedNations` and moved from `gistCore` to `gistDeprecated`.  A `gist:CountryGovernment` must be recognized by some organization, but not specifically the United Nations.
-- Rationale: The only function of this individual was in the definition of `gist:CountryGovernment`, but the recognizing institution of a country government is implementation-dependent and thus does not belong in gist. Those wishing to refer to the United Nations should use an existing URI issued by an authoritative source.
-- Impact: `gist:_unitedNations` is still available for use in `gistDeprecated`. The definition of `gist:CountryGovernment` has been relaxed with the removal of an incorrect requirement; client ontologies can subclass with their desired recognizing body.
-- Issue: [#207](https://github.com/semanticarts/gist/issues/207).
-
-*Trivial corrections to axioms in the definition of some geo terms*
-
-- Description: Trivial corrections to axioms in the definitions of `gist:GeoRoute`, `gist:geoContains`, and `gist:GeoRoute`.
-- Rationale: Bug fixes.
-- Impact: None.
-- Issues: [#64](https://github.com/semanticarts/gist/issues/64), [#334](https://github.com/semanticarts/gist/issues/334), [#361](https://github.com/semanticarts/gist/issues/361).
+Release 9.4.0
+-----
 
-*Changed ontology edit format from RDF/XML (.owl) to Turtle (.ttl)*
+### Minor Updates
 
-- Description: OWL files are now stored in the repository as Turtle rather than RDF/XML. The release package will include RDF/XML, Turtle, and JSON-LD files.
-- Rationale: Turtle is an easier format to read and edit. Users may want to use any one of these three common serializations.
-- Issues: [#223](https://github.com/semanticarts/gist/issues/223), [#319](https://github.com/semanticarts/gist/issues/319).
+- 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).
+- Replaced `gist:Weight` with `gist:Mass` in all contexts. Issue [#105](https://github.com/semanticarts/gist/issues/105).
 
-*Added release notes template*
+### Patch Updates
 
-- Description: Added release notes template to be followed by contributors submitting a PR.
-- Rationale: Standardize release note format for readability.
-- Issue: [#338](https://github.com/semanticarts/gist/issues/338).
+- Made `gist:hasPhysicalLocation` transitive. Issue [#109](https://github.com/semanticarts/gist/issues/109).
+- Deprecated `gist:_unitedNations`. Issue [#207](https://github.com/semanticarts/gist/issues/207).
+- Made trivial corrections to axioms in the definition of some geo terms. Issues [#64](https://github.com/semanticarts/gist/issues/64), [#334](https://github.com/semanticarts/gist/issues/334), [#361](https://github.com/semanticarts/gist/issues/361).
+- Changed ontology edit format from RDF/XML (.owl) to Turtle (.ttl). Issues [#223](https://github.com/semanticarts/gist/issues/223), [#319](https://github.com/semanticarts/gist/issues/319).
+- Added release notes template. Issue [#338](https://github.com/semanticarts/gist/issues/338).
 
 Import URL: <https://ontologies.semanticarts.com/o/gistCore9.4.0>.
 
@@ -82,7 +60,7 @@ Release 9.2.0
 - Replaced all "xs" namespace prefixes for XML Schema with "xsd". Corrects issue [#158](https://github.com/semanticarts/gist/issues/158).
 - Corrected gist:convertToBase value for gist:_minute from 1.0 to 60.0. Fixes issue [#82](https://github.com/semanticarts/gist/issues/82).
 - Added initial draft of in-progress gist style guide. Fixes issue [#163](https://github.com/semanticarts/gist/issues/163).
-- Added documentation of change and release management process. Fixes issue [#233](https://github.com/semanticarts/gist/issues/233).
+- Added documentation of change and release management process. Fixes issue [#233](<https://github.com/semanticarts/gist/issues/233>.
 - Added guidelines for submission of GitHub issues and pull requests. Fixes issue [#190](https://github.com/semanticarts/gist/issues/190).
 - Remove defunct tools and documentation. Fixes issue [#193](https://github.com/semanticarts/gist/issues/193).
 - Include direct imports of all gist modules in gistCore. Fixes issue [#80](https://github.com/semanticarts/gist/issues/80).
@@ -286,8 +264,8 @@ Release Notes gist 7.0
 gist 7.0 is a major upgrade from our last released version (6.7.1). The main differences are:
 
 - gist 7.0 is extremely modular. There are 18 modules that can be used collectively or in subsets if you don't need all the concepts in gist.
-- gist 7.0 is more elegant than its predecessors. We have reduced the number of top level concepts that everything else derives from to 12. And these 12 concepts are not philosophical abstractions like endurants and perdurants, or qualia, there are normal terms whose definitions   are quite close to what you already believe.
-- gist 7.0 has more extensive and more-fine grained disjointness at the highest level. It turns out that in order for an upper ontology to help you avoid making logical errors in your derived enterprise or application ontology, it needs to make use of disjointness. Without  disjointness, the reasoner does not find logic errors.
+- gist 7.0 is more elegant than its predecessors. We have reduced the number of top level concepts that everything else derives from to 12. And these 12 concepts are not philosophical abstractions like endurants and perdurants, or qualia, there are normal terms whose definitions are quite close to what you already believe.
+- gist 7.0 has more extensive and more-fine grained disjointness at the highest level. It turns out that in order for an upper ontology to help you avoid making logical errors in your derived enterprise or ontology, it needs to make use of disjointness. Without  disjointness, the reasoner does not find logic errors.
 
 For documentation and OWL files regarding terms that were deprecated when moving from version 6.7.1 to 7.0, please see the sub-folder called "Deprecated terms from gist6.7.1".
 

docs/gistStyleGuide.md

@@ -19,8 +19,9 @@ Serialization
 
 - gist OWL files are serialized in RDF Turtle
 - The [EDM Council's RDF serialization tool, rdf-toolkit.jar,](https://github.com/edmcouncil/rdf-toolkit) should be run before every commit in order to standardize formatting and eliminate noise in git diffs.
-- It is recommended to run this as a [pre-commit hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) in your git repository to ensure that it is done every time. You can use the [pre-commit hook provided by the EDM Council] (<https://github.com/edmcouncil/rdf-toolkit/blob/master/etc/git-hook/pre-commit).>
-  - Forthcoming: Information on an alternative pre-commit hook
+- It is recommended to run this as a [pre-commit hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) in your git repository to ensure that it is done every time.
+  In order to use the standard settings, copy the provided `pre-commit` script from the `tools/` directory in the repository to `.git/hooks/` after the repository is cloned,
+  and ensure that `JAVA_HOME` is set in your environment. This script will only format RDF files, ignoring all others.
 
 Naming
 -----
@@ -62,6 +63,48 @@ Naming
 
 We adopt sentence over title case because the latter, while technically well-defined, has more complex rules and can introduce inconsistencies when implemented by different users.
 
+### Annotations
+
+gist uses SKOS annotations rather than `rdfs:label` and `rdfs:comment`. The accepted annotations, intended use, and previous usage are shown in the following tables. Refer to the [SKOS ontology](http://www.w3.org/2004/02/skos/core) for formal definitions.
+
+*Preferred SKOS annotations*
+
+| Annotation | Use | Instead Of |
+| ---------: | --- |:---------|
+| `skos:prefLabel` | Preferred label | `rdfs:label` |
+| `skos:altLabel`  | Alternative label, where relevant | n/a |
+| `skos:definition` | Definition | `rdfs:comment` |
+| `skos:scopeNote` | Additional clarifying comments about the meaning or usage of a term | `rdfs:comment` |
+| `skos:example`   | One or more examples  | `rdfs:comment` |
+| `skos:editorialNote` | Notes for editors | `rdfs:comment` |
+
+*RDFS annotations*
+
+Certain RDFS annotations are recommended where there is no SKOS equivalent.
+
+| Annotation | Use |
+| ---------: | --- |
+| `rdfs:seeAlso` | Indicates a resource that may provide additional information about the subject. Preferably points to a web page or RDF resource rather than text. |
+| `rdfs:isDefinedBy` | Identifies the ontology module the term is defined in. Added automatically during gist release bundling and does not needed to be added by hand. |
+
+*Use only rarely*
+
+| Annotation | Comment |
+| ---------: | ------- |
+| `skos:changeNote` | Normally change notes are provided by the git history or version comparison. |
+| `skos:historyNote` | Normally change notes are provided by the git history or version comparison. |
+| `skos:note` | A more specific annotation is preferred. |
+
+*Do not use*
+| Annotation | Instead Use |
+| ---------: | ----------- |
+| `rdfs:label` | `skos:prefLabel` |
+| `rdfs:comment` | All other annotations, especially `skos:scopeNote` and `skos:example` |
+
+#### Rationale
+
+SKOS annotations allow a more fine-grained approach to human-readable documentation. This change also aligns with emerging common practice.
+
 Documentation
 -----