diff --git a/docs/ReleaseNotes.md b/docs/ReleaseNotes.md index 95ce83a7..df2ecc45 100644 --- a/docs/ReleaseNotes.md +++ b/docs/ReleaseNotes.md @@ -10,6 +10,9 @@ Release 10.0.0 and [RFC6838](https://tools.ietf.org/html/rfc6838). Issue [#434](). - Renamed `gist:decimalValue` to `gist:numericValue` and expanded property range to include all numeric data types supported by OWL. Issue [#171]() +- Refactored ordered collection model. Issue [#112]() + - 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 sub-property of `gist:start` rather than `gist:actualStart`. @@ -17,7 +20,7 @@ Release 10.0.0 - `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 `memberOf` a `Network`. - + ### 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) diff --git a/docs/gistStyleGuide.md b/docs/gistStyleGuide.md index eda2b4a8..0fc7cf81 100644 --- a/docs/gistStyleGuide.md +++ b/docs/gistStyleGuide.md @@ -1,19 +1,39 @@ -gist Style Guide [ IN PROGRESS ] +gist Style Guide ===== -Purpose of this document +- [Purpose of this style guide](#purpose-of-this-style-guide) +- [OWL Version](#owl-version) +- [Serialization](#serialization) +- [Naming: Local Names](#naming-local-names) + - [Classes](#classes) + - [Properties](#properties) + - [All](#all) +- [Naming: Labels](#naming-labels) + - [Classes](#classes-1) + - [Properties](#properties-1) + - [gist Definition of Title Case](#gist-definition-of-title-case) +- [Annotations](#annotations) + - [Conventions](#conventions) + - [Rationale](#rationale) +- [Documentation](#documentation) + +Purpose of this style guide ----- -The purpose of this document is two-fold: +The purpose of this evolving document is two-fold: - Define and implement conventions in order to standardize gist. - Articulate what we consider best or "better" practices for ontology design and implementation. +----- + OWL Version ----- gist uses OWL 2 DL. +----- + Serialization ----- @@ -23,12 +43,12 @@ Serialization 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 ----- -### Local names +Naming: Local Names +----- -#### Classes +### Classes - Camelcase with initial uppercase - Acronyms are also camelcased so that word boundaries are unambiguous. @@ -37,36 +57,37 @@ Naming - Alphanumeric characters only. - Example: `Isbn10`, not `Isbn-10` or `ISBN-10`. -#### Properties +### Properties - Camelcase with initial lowercase - Acronyms as above -#### All +### All - No non-standard abbreviations. E.g., `hasUoM` should be `hasUnitOfMeasure`. -### Labels +Naming: Labels +----- The following conventions apply to `skos:prefLabel` but not `skos:altLabel`. -#### Classes +### Classes - Title case (see definition of title case below) - Normalized to natural language standards. E.g., hyphens inserted, acronyms in all caps, etc. - Examples: _AMA Guideline_, _ISBN-10_ -#### Properties +### Properties - Lower case - Normalized to natural language standards. E.g., hyphens inserted, acronyms in all caps, proper nouns capitalized, etc. - Examples: _has unit of measure_, _has SSN_, _unit symbol Unicode_ -#### gist Definition of Title Case +### gist Definition of Title Case The rules of title case are not universally standardized; standardization is only at the level of house styles and individual style guides. Most English style guides agree that the first and last words should always be capitalized, while articles, short prepositions, and some conjunctions should not be. Other rules about the capitalization vary. -gist style guide for title case: +This style guide defines the rules for title case as follows: - Capitalize: - First and last words @@ -79,7 +100,12 @@ gist style guide for title case: - Acronyms in all caps (e.g., _SSN_, _ISBN_) - Capitalize everything else -### Annotations +----- + +Annotations +----- + +### Conventions 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. @@ -117,10 +143,12 @@ Certain RDFS annotations are recommended where there is no SKOS equivalent. | `rdfs:label` | `skos:prefLabel` | | `rdfs:comment` | All other annotations, especially `skos:scopeNote` and `skos:example` | -#### Rationale +### Rationale SKOS annotations allow a more fine-grained approach to human-readable documentation. This change also aligns with emerging common practice. +----- + Documentation ----- diff --git a/gistCore.ttl b/gistCore.ttl index 34b8df72..2f673c44 100644 --- a/gistCore.ttl +++ b/gistCore.ttl @@ -1758,51 +1758,47 @@ gist:Offer gist:OrderedCollection a owl:Class ; rdfs:subClassOf gist:Collection ; + owl:equivalentClass [ + owl:intersectionOf ( + gist:Collection + [ + a owl:Restriction ; + owl:onProperty gist:hasOrderedMember ; + owl:someValuesFrom owl:Thing ; + ] + ) ; + ] ; skos:definition "A collection where the members are in a fixed sequence."^^xsd:string ; skos:prefLabel "Ordered Collection"^^xsd:string ; + skos:scopeNote "Empty collections are not supported at this time."^^xsd:string ; . -gist:OrdinalCollection - a owl:Class ; - rdfs:subClassOf - gist:OrderedCollection , - [ - a owl:Restriction ; - owl:onProperty gist:hasOrderedMember ; - owl:allValuesFrom gist:OrdinalMember ; - ] - ; - skos:definition "An Ordered Collection where no item can be of the same rank as any other item. In mathematical terms, this is a ?strict total order?."^^xsd:string ; - skos:prefLabel "Ordinal Collection"^^xsd:string ; - . - -gist:OrdinalMember +gist:OrderedMember a owl:Class ; - rdfs:subClassOf - gist:Category , - [ - a owl:Class ; - owl:unionOf ( - [ - a owl:Restriction ; - owl:onProperty gist:directlyPrecededBy ; - owl:someValuesFrom gist:OrdinalMember ; - ] - [ - a owl:Restriction ; - owl:onProperty gist:directlyPrecedes ; - owl:someValuesFrom gist:OrdinalMember ; - ] - ) ; - ] - ; - owl:equivalentClass [ - a owl:Restriction ; - owl:onProperty gist:orderedMemberOf ; - owl:someValuesFrom gist:OrdinalCollection ; + rdfs:subClassOf [ + a owl:Class ; + owl:unionOf ( + [ + a owl:Restriction ; + owl:onProperty gist:directlyPrecededBy ; + owl:someValuesFrom gist:OrderedMember ; + ] + [ + a owl:Restriction ; + owl:onProperty gist:directlyPrecedes ; + owl:someValuesFrom gist:OrderedMember ; + ] + [ + a owl:Restriction ; + owl:onProperty gist:sequence ; + owl:someValuesFrom xsd:integer ; + ] + ) ; ] ; - skos:definition "A member of an Ordinal Collection. It necessarily precedes or is preceded by another Ordinal Member in the same collection. (This last condition cannot be formally stated in OWL)."^^xsd:string ; - skos:prefLabel "Ordinal Member"^^xsd:string ; + skos:definition "A member of an ordered collection that serves as a proxy for a real world item, which can appear in different orders in different collections. The ordered member appears in exactly one ordered collection."^^xsd:string ; + skos:example "A person may rank 12th in the Boston Marathon but 29th in the New York City Marathon."^^xsd:string ; + skos:prefLabel "Ordered Member"^^xsd:string ; + skos:scopeNote "An ordered member points to the real world item via the providesOrderFor property. Ordering information is represented either as a number in a sequence, or by preceding or following another ordered member. The ordered collection is linked to the ordered member via the property hasOrderedMember."^^xsd:string ; . gist:Organization @@ -3313,13 +3309,14 @@ gist:hasNavigationalParent gist:hasOrderedMember a - owl:InverseFunctionalProperty , - owl:ObjectProperty + owl:ObjectProperty , + owl:InverseFunctionalProperty ; rdfs:subPropertyOf gist:hasMember ; - owl:inverseOf gist:orderedMemberOf ; - skos:definition "An inverse functional version of hasMember to ensure that no OrderedMember can be in more than one OrderedCollection., which can quickly lead to problems."^^xsd:string ; + rdfs:range gist:OrderedMember ; + skos:definition "Relates an ordered collection to an ordered member that belongs to it."^^xsd:string ; skos:prefLabel "has ordered member"^^xsd:string ; + skos:scopeNote "This property is inverse functional because no ordered member can be in more than one ordered collection."^^xsd:string ; . gist:hasPart @@ -3431,8 +3428,8 @@ gist:hasTag gist:hasUniqueNavigationalParent a - owl:FunctionalProperty , - owl:ObjectProperty + owl:ObjectProperty , + owl:FunctionalProperty ; rdfs:subPropertyOf gist:hasNavigationalParent ; skos:definition "Used for taxos that must have single parents"^^xsd:string ; @@ -3441,8 +3438,8 @@ gist:hasUniqueNavigationalParent gist:hasUniqueSuperCategory a - owl:FunctionalProperty , - owl:ObjectProperty + owl:ObjectProperty , + owl:FunctionalProperty ; rdfs:subPropertyOf gist:hasSuperCategory ; skos:definition "Used for taxos that must have single parents"^^xsd:string ; @@ -3459,8 +3456,8 @@ gist:hasUoM gist:identifiedBy a - owl:InverseFunctionalProperty , - owl:ObjectProperty + owl:ObjectProperty , + owl:InverseFunctionalProperty ; rdfs:range gist:ID ; owl:inverseOf gist:identifies ; @@ -3470,8 +3467,8 @@ gist:identifiedBy gist:identifies a - owl:FunctionalProperty , - owl:ObjectProperty + owl:ObjectProperty , + owl:FunctionalProperty ; skos:definition "The thing the identifier refers to."^^xsd:string ; skos:prefLabel "identifies"^^xsd:string ; @@ -3648,15 +3645,6 @@ gist:offspringOf skos:prefLabel "offspring of"^^xsd:string ; . -gist:orderedMemberOf - a - owl:FunctionalProperty , - owl:ObjectProperty - ; - skos:definition "An inverse of hasOrderedMember"^^xsd:string ; - skos:prefLabel "ordered member of"^^xsd:string ; - . - gist:owns a owl:ObjectProperty ; rdfs:domain [ @@ -3754,6 +3742,16 @@ gist:produces skos:prefLabel "produces"^^xsd:string ; . +gist:providesOrderFor + a + owl:ObjectProperty , + owl:FunctionalProperty + ; + rdfs:domain gist:OrderedMember ; + skos:definition "Links a member of an ordered collection to the real-world item it represents in that collection."^^xsd:string ; + skos:prefLabel "provides order for"^^xsd:string ; + . + gist:rangeIncludes a owl:AnnotationProperty ; rdfs:subPropertyOf skos:scopeNote ; diff --git a/tools/pre-commit b/tools/pre-commit index b254a683..0cb0fd1b 100755 --- a/tools/pre-commit +++ b/tools/pre-commit @@ -180,7 +180,7 @@ __log_config__ log "Launching the sesame-serializer with --source ${file}" set -x - "${java_exe}" -Xmx1g "-Dorg.clapper.avsl.config=${logcfg}" -cp "${RDF_TOOLKIT_JAR}" org.edmcouncil.rdf_toolkit.SesameRdfFormatter \ + "${java_exe}" -Xmx1g "-Dorg.clapper.avsl.config=${logcfg}" -jar "${RDF_TOOLKIT_JAR}" \ --source "${file}" \ --target "${file}X" \ --target-format ${tfmt} \ diff --git a/tools/rdf-toolkit.jar b/tools/rdf-toolkit.jar index f6fca0ba..dedee9f2 100644 Binary files a/tools/rdf-toolkit.jar and b/tools/rdf-toolkit.jar differ