From ffb4424c7027b55aff869dc74464316cd8788548 Mon Sep 17 00:00:00 2001 From: caufieldjh Date: Tue, 11 Feb 2025 15:56:45 -0500 Subject: [PATCH 1/4] Remove principles --- principles/Makefile | 60 ---- principles/all.yml | 49 --- principles/checks/fp_001.md | 405 ----------------------- principles/checks/fp_002.md | 60 ---- principles/checks/fp_003.md | 238 ------------- principles/checks/fp_004.md | 109 ------ principles/checks/fp_005.md | 66 ---- principles/checks/fp_006.md | 106 ------ principles/checks/fp_007.md | 304 ----------------- principles/checks/fp_008.md | 89 ----- principles/checks/fp_009.md | 63 ---- principles/checks/fp_011.md | 64 ---- principles/checks/fp_012.md | 117 ------- principles/checks/fp_016.md | 132 -------- principles/checks/fp_020.md | 57 ---- principles/fp-000-summary.md | 43 --- principles/fp-001-open.md | 169 ---------- principles/fp-002-format.md | 48 --- principles/fp-003-uris.md | 68 ---- principles/fp-004-versioning.md | 72 ---- principles/fp-005-delineated-content.md | 49 --- principles/fp-006-textual-definitions.md | 114 ------- principles/fp-007-relations.md | 37 --- principles/fp-008-documented.md | 87 ----- principles/fp-009-users.md | 127 ------- principles/fp-010-collaboration.md | 43 --- principles/fp-011-locus-of-authority.md | 55 --- principles/fp-012-naming-conventions.md | 32 -- principles/fp-013-notification.md | 77 ----- principles/fp-016-maintenance.md | 29 -- principles/fp-020-responsiveness.md | 71 ---- 31 files changed, 3040 deletions(-) delete mode 100644 principles/Makefile delete mode 100644 principles/all.yml delete mode 100644 principles/checks/fp_001.md delete mode 100644 principles/checks/fp_002.md delete mode 100644 principles/checks/fp_003.md delete mode 100644 principles/checks/fp_004.md delete mode 100644 principles/checks/fp_005.md delete mode 100644 principles/checks/fp_006.md delete mode 100644 principles/checks/fp_007.md delete mode 100644 principles/checks/fp_008.md delete mode 100644 principles/checks/fp_009.md delete mode 100644 principles/checks/fp_011.md delete mode 100644 principles/checks/fp_012.md delete mode 100644 principles/checks/fp_016.md delete mode 100644 principles/checks/fp_020.md delete mode 100644 principles/fp-000-summary.md delete mode 100644 principles/fp-001-open.md delete mode 100644 principles/fp-002-format.md delete mode 100644 principles/fp-003-uris.md delete mode 100644 principles/fp-004-versioning.md delete mode 100644 principles/fp-005-delineated-content.md delete mode 100644 principles/fp-006-textual-definitions.md delete mode 100644 principles/fp-007-relations.md delete mode 100644 principles/fp-008-documented.md delete mode 100644 principles/fp-009-users.md delete mode 100644 principles/fp-010-collaboration.md delete mode 100644 principles/fp-011-locus-of-authority.md delete mode 100644 principles/fp-012-naming-conventions.md delete mode 100644 principles/fp-013-notification.md delete mode 100644 principles/fp-016-maintenance.md delete mode 100644 principles/fp-020-responsiveness.md diff --git a/principles/Makefile b/principles/Makefile deleted file mode 100644 index 05391bb..0000000 --- a/principles/Makefile +++ /dev/null @@ -1,60 +0,0 @@ -# Collect the list of query files for report. -SCRIPTS := build/fp_001.py build/fp_002.py build/fp_003.py build/fp_004.py \ -build/fp_005.py build/fp_006.py build/fp_007.py build/fp_008.py build/fp_009.py \ -build/fp_011.py build/fp_012.py build/fp_016.py -DOCS := $(foreach x, $(SCRIPTS), checks/$(notdir $(basename $(x))).md) - -# FP ID to the principle name -1 = Open -2 = 'Common Format' -3 = URI -4 = Versioning -5 = Scope -6 = 'Textual Definitions' -7 = Relations -8 = Documentation -9 = 'Documented Plurality of Users' -11 = 'Locus of Authority' -12 = 'Naming Conventions' -16 = Maintenance - -# Generate all check docs -all: clean -scripts: $(SCRIPTS) - -# Make the directories -checks build: - mkdir -p $@ - -# Download the scripts from the OBO-Dashboard repo -.PHONY: build/fp_%.py -build/fp_%.py: | build - curl -Lk -o $@ https://raw.githubusercontent.com/OBOFoundry/OBO-Dashboard/master/util/dashboard/$(notdir $@) - -# Build the MD page from the check script -checks/fp_%.md: build/fp_%.py | $(SCRIPTS) checks - $(eval ID := $(subst 0,,$(subst fp_,,$(notdir $(basename $@))))) - if [ $(ID) == 1 ]; then export TITLE=$(1); \ - elif [ $(ID) == 2 ]; then export TITLE=$(2); \ - elif [ $(ID) == 3 ]; then export TITLE=$(3); \ - elif [ $(ID) == 4 ]; then export TITLE=$(4); \ - elif [ $(ID) == 5 ]; then export TITLE=$(5); \ - elif [ $(ID) == 6 ]; then export TITLE=$(6); \ - elif [ $(ID) == 7 ]; then export TITLE=$(7); \ - elif [ $(ID) == 8 ]; then export TITLE=$(8); \ - elif [ $(ID) == 9 ]; then export TITLE=$(9); \ - elif [ $(ID) == 11 ]; then export TITLE=$(11); \ - elif [ $(ID) == 12 ]; then export TITLE=$(12); \ - elif [ $(ID) == 16 ]; then export TITLE=$(16); \ - fi; \ - echo "---\nlayout: check\nid: $(ID)\ntitle: $$TITLE Automated Check\n---\n" > $@ - tail -n+3 $< \ - | sed 's/^##//' \ - | sed 's/^ //' \ - | awk '!found && /import/ { print "```python"; found=1 } 1' \ - >> $@ - echo '```' >> $@ - - -clean: $(DOCS) - rm -rf build \ No newline at end of file diff --git a/principles/all.yml b/principles/all.yml deleted file mode 100644 index e39c7cd..0000000 --- a/principles/all.yml +++ /dev/null @@ -1,49 +0,0 @@ -principles: -- id: fp-000-summary - layout: principle - title: Overview -- id: fp-001-open - layout: principle - title: Open (principle 1) -- id: fp-002-format - layout: principle - title: Common Format (principle 2) -- id: fp-003-uris - layout: principle - title: URI/Identifier Space (principle 3) -- id: fp-004-versioning - layout: principle - title: Versioning (principle 4) -- id: fp-005-delineated-content - layout: principle - title: Scope (principle 5) -- id: fp-006-textual-definitions - layout: principle - title: Textual Definitions (principle 6) -- id: fp-007-relations - layout: principle - title: Relations (principle 7) -- id: fp-008-documented - layout: principle - title: Documentation (principle 8) -- id: fp-009-users - layout: principle - title: Documented Plurality of Users (principle 9) -- id: fp-010-collaboration - layout: principle - title: Commitment To Collaboration (principle 10) -- id: fp-011-locus-of-authority - layout: principle - title: Locus of Authority (principle 11) -- id: fp-012-naming-conventions - layout: principle - title: Naming Conventions (principle 12) -- id: fp-013-notification - layout: principle - title: Notification of Changes (principle 13) -- id: fp-016-maintenance - layout: principle - title: Maintenance (principle 16) -- id: fp-020-responsiveness - layout: principle - title: Responsiveness (principle 20) diff --git a/principles/checks/fp_001.md b/principles/checks/fp_001.md deleted file mode 100644 index 7dea596..0000000 --- a/principles/checks/fp_001.md +++ /dev/null @@ -1,405 +0,0 @@ ---- -layout: check -id: fp_001 -title: Open Automated Check ---- - -## [Open](http://obofoundry.org/principles/fp-001-open.html) Automated Check - -Discussion on this check can be [found here](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/1019). - -### Requirements - -1. The ontology **must** have a license both in the registry data and in the ontology file. -2. The license **must** be the same in both files. -3. The license _should_ be one of the CC0 or CC-BY licenses. - -### Fixes - -#### Choosing a license - -See [Open Recommendations](http://obofoundry.org/principles/fp-001-open.html#recommendations) for appropriate licenses. - -#### Adding a license to the registry data - -First, read the [FAQ](http://obofoundry.github.io/faq/how-do-i-edit-metadata.html) on how to edit the metadata for your ontology. Then, add the following to your [metadata file](https://github.com/OBOFoundry/OBOFoundry.github.io/tree/master/ontology) (replacing with the correct license and license label): - -``` -license: - url: http://creativecommons.org/licenses/by/4.0/ - label: CC-BY 4.0 -``` - -#### Adding a license to the ontology file - -See [Open Implementation](http://obofoundry.org/principles/fp-001-open.html#implementation) for details on adding license to OWL and OBO files. - -### Implementation - -The registry data entry is validated with JSON schema using the [license schema](https://raw.githubusercontent.com/OBOFoundry/OBOFoundry.github.io/master/util/schema/license.json). The license schema ensures that a license entry is present and that the entry has a `url` and `label`. The license schema also checks that the license is one of the CC0 or CC-BY licenses. OWL API is then used to check the ontology as an `OWLOntology` object. Annotations on the ontology are retrieved and the `dcterms:license` property is found. The python script ensures that the correct `dcterms:license` property is used. The script compares this license to the registry license to ensure that they are the same. - -```python -import jsonschema -import dash_utils - - -def is_open(ontology, data): - """Check FP 1 - Open. - - This method checks the following: - - is the registry license present? (ERROR) - - is the registry license a valid open license? (WARN) - - is the ontology license present? (ERROR) - - does the ontology license match the registry license? (ERROR) - - does the ontology license use the correct property? (WARN) - The registry license is checked by validation against the license schema. - The ontology license is retrieved from the OWLOntology object. - - Args: - ontology (OWLOntology): ontology object - data (dict): parsed ontology registry data from YAML file - - Returns: - ERROR, WARN, INFO, or PASS string with optional message. - """ - - v = OpenValidator(ontology, data) - - loadable = False - if ontology: - loadable = True - - return process_results(v.registry_license, - v.ontology_license, - v.is_open, - loadable, - v.correct_property, - v.matches_ontology) - - -class OpenValidator(): - """Validator for FP 1 - Open on OWLOntology objects. - - Attributes: - registry_license (str): license URL from registry data - is_open (bool): True if registry license is CC0 or CC-BY (None if - missing) - ontology_license (str): license URL from ontology - correct_property (bool): True if license annotation uses the correct DC - licenses property (None if missing) - matches_ontology (bool): True if registry licenses matches ontology - license (None if missing) - """ - - def __init__(self, ontology, data): - """Instantiate an OpenValidator. - - Args: - ontology (OWLOntology): ontology object - data (dict): parsed ontology registry data from YAML file - """ - - self.registry_license = None - if 'license' in data and 'url' in data['license']: - self.registry_license = data['license']['url'] - - self.is_open = None - if self.registry_license is not None: - self.is_open = check_registry_license(data) - - self.ontology_license = None - self.correct_property = None - # set ontology_license and correct_property - self.check_ontology_license(ontology) - - self.matches_ontology = compare_licenses(self.registry_license, - self.ontology_license) - - def check_ontology_license(self, ontology): - """Check if ontology license exists and uses correct propety. - - Retrieve the license in the header and the annotation property used. - Set ontology_license (string or None) and correct_property (True, - False, or None). - - Args: - ontology (OWLOntology): ontology object - """ - - # if the ontology is missing, we could not load it - if ontology is None: - return - - # search the annotations to find a license - annotations = ontology.getAnnotations() - license = dash_utils.get_ontology_annotation_value(annotations, - license_prop) - bad_license = dash_utils.get_ontology_annotation_value( - annotations, bad_license_prop) - - if license: - self.ontology_license = license - self.correct_property = True - elif bad_license: - self.ontology_license = bad_license - self.correct_property = False - - -def big_is_open(file, data): - """Check FP 1 - Open. - - This method checks the following: - - is the registry license present? (ERROR) - - is the registry license a valid open license? (WARN) - - is the ontology license present? (ERROR) - - does the ontology license match the registry license? (ERROR) - - does the ontology license use the correct property? (WARN) - The registry license is checked by validation against the license schema. - The ontology license is retrieved from the ontology file. - - Args: - file (str): path to ontology file - data (dict): parsed ontology registry data from YAML file - - Returns: - ERROR, WARN, INFO, or PASS string with optional message. - """ - - v = BigOpenValidator(file, data) - return process_results(v.registry_license, - v.ontology_license, - v.is_open, - None, - v.correct_property, - v.matches_ontology) - - -class BigOpenValidator(): - """Validator for FP 1 - Open on big ontology files. - - Attributes: - registry_license (str): license URL from registry data - is_open (bool): True if registry license is CC0 or CC-BY (None if - missing) - ontology_license (str): license URL from ontology - correct_property (bool): True if license annotation uses the correct DC - licenses property (None if missing) - matches_ontology (bool): True if registry licenses matches ontology - license (None if missing) - """ - - def __init__(self, file, data): - """Instantiate a BigOpenValidator. - - Args: - file (str): path to ontology file - data (dict): parsed ontology registry data from YAML file - """ - - self.registry_license = None - if 'license' in data and 'url' in data['license']: - self.registry_license = data['license']['url'] - - self.is_open = None - if self.registry_license is not None: - self.is_open = check_registry_license(data) - - self.ontology_license = None - self.correct_property = None - # set ontology_license and correct_property - self.check_ontology_license(file) - - self.matches_ontology = compare_licenses(self.registry_license, - self.ontology_license) - - def check_ontology_license(self, file): - """Check if ontology license exists and uses correct propety. - - Retrieve the license in the header and the annotation property used. - Set ontology_license (string or None) and correct_property (True, - False, or None). - - Args: - file (str): path to ontology file - """ - - dc11 = None - dcterms = None - rdf = None - owl = None - prefixes = True - - with open(file, 'r') as f: - for line in f: - if prefixes: - # we need to know the prefixes - if 'http://purl.org/dc/elements/1.1' in line: - dc11 = dash_utils.get_prefix(line) - elif 'http://purl.org/dc/terms' in line: - dcterms = dash_utils.get_prefix(line) - elif 'http://www.w3.org/1999/02/22-rdf-syntax-ns#' in line: - rdf = dash_utils.get_prefix(line) - elif 'http://www.w3.org/2002/07/owl#' in line: - owl = dash_utils.get_prefix(line) - elif owl and '{0}:Ontology'.format(owl) in line: - prefixes = False - elif ''.format(owl) in line: - # we don't care about anything outside the header - # if we get here, no license was found - break - - elif dc11 and '{0}:license'.format(dc11) in line: - # incorrect dc license - if rdf and '{0}:resource'.format(rdf) in line: - self.ontology_license = dash_utils.get_resource_value( - line) - self.correct_property = False - else: - self.ontology_license = dash_utils.get_literal_value( - line) - self.correct_property = False - return - - elif dcterms and '{0}:license'.format(dcterms) in line: - # correct dc license - if rdf and '{0}:resource'.format(rdf) in line: - self.ontology_license = dash_utils.get_resource_value( - line) - self.correct_property = True - else: - self.ontology_license = dash_utils.get_literal_value( - line) - self.correct_property = True - return - - -# ---------- UTILITY METHODS ---------- # - - -def check_registry_license(data): - """Use the JSON license schema to validate the registry data. - - This ensures that the license is present and one of the CC0 or CC-BY - licenses. - - Args: - data (dict): parsed ontology registry data from YAML file - - Return: - True if data passes validation. - """ - - try: - jsonschema.validate(data, license_schema) - return True - except jsonschema.exceptions.ValidationError as ve: - return False - - -def compare_licenses(registry_license, ontology_license): - """Compare the registry and ontology licenses. - - Args: - registry_license (str): license URL from the registry - ontology_license (str): license URL from the ontology - - Return: - True if registry license matches ontology licences; - False if the licenses do not match; - None if one or both licenses are missing. - """ - - if ontology_license is None or registry_license is None: - return None - - # normalize http vs https - fmt_ontology_license = ontology_license.replace('https', 'http').strip() - fmt_registry_license = registry_license.replace('https', 'http').strip() - return (fmt_ontology_license == fmt_registry_license) - - -def process_results(registry_license, - ontology_license, - is_open, - loadable, - correct_property, - matches_ontology): - """Process the results of the validation to create a cell for the dashboard - table in the format '{LEVEL}|{OPTIONAL MESSAGE}'. - - Args: - registry_license (str): license URL from the registry data - ontology_license (str): license URL from the ontology - is_open (bool): if True, license is CC0 or CC-BY; - if False, license is not open; - if None, registry license is missing - loadable (bool): if True, ontology was loaded; - if False, ontology could not be loaded; - if None, no attempt to load was made (big) - correct_property (bool): if True, correct DC license property was used; - if False, wrong DC license property was used; - if None, the ontology license is missing - matches_ontology (bool): if True, the registry license matches the - ontology license; - if False, the registry license does not match; - if None, one or both licenses are missing - - Return: - '{LEVEL}|{OPTIONAL MESSAGE}' where LEVEL is one of PASS, INFO, WARN, or - ERROR. The OPTIONAL MESSAGE explains the issues on a non-PASS level. - """ - - # error messages - missing_registry_license = 'Missing registry license.' - missing_ontology_license = 'Missing ontology license.' - load_err = 'Unable to load ontology.' - not_open = 'Registry license \'{0}\' is not a valid open license.' - wrong_prop = 'License should use property \'{0}\'.'.format(license_prop) - no_match = 'Ontology license \'{0}\' does not match registry license\ -\'{1}\'.' - - issues = [] - level = 'PASS' - - # loadable = None for big ontologies - if loadable is False: - level = 'ERROR' - issues.append(load_err) - - # is_open = None if missing registry license - if is_open is False: - level = 'WARN' - issues.append(not_open.format(registry_license)) - - # correct_property = None if missing ontology license - if correct_property is False: - level = 'WARN' - issues.append(wrong_prop) - - if not ontology_license: - level = 'ERROR' - issues.append(missing_ontology_license) - - # matches_ontology = None if missing ontology licenese - if matches_ontology is False: - level = 'ERROR' - issues.append(no_match.format(ontology_license, registry_license)) - - if not registry_license: - level = 'ERROR' - issues.append(missing_registry_license) - - if len(issues) == 0: - return {'status': level} - - return {'status': level, 'comment': ' '.join(issues)} - - -# correct dc license property namespace -license_prop = 'http://purl.org/dc/terms/license' -# incorrect dc license property namespace -bad_license_prop = 'http://purl.org/dc/elements/1.1/license' - -# license JSON schema for registry validation -license_schema = dash_utils.load_schema('dependencies/license.json') -``` diff --git a/principles/checks/fp_002.md b/principles/checks/fp_002.md deleted file mode 100644 index 0b7290d..0000000 --- a/principles/checks/fp_002.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -layout: check -id: 2 -title: Common Format Automated Check ---- - -## [Common Format](http://obofoundry.org/principles/fp-002-format.html) Automated Check - -Discussion on this check can be [found here](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/1018). - -### Requirements - -1. Released ontology **must** be in RDF/XML format - -### Fixes - -See the [Common Format Recommendations](http://obofoundry.org/principles/fp-002-format.html#recommendations). [ROBOT](http://robot.obolibrary.org/convert) offers functionality to convert a variety of formats, including OBO, to RDF/XML. Protégé allows you to save ontologies in RDF/XML, as well. The [Ontology 101 Tutorial](https://ontology101tutorial.readthedocs.io/en/latest/StartingProtege.html) has directions on starting and saving in Protégé. - -### Implementation - -Current implementation attempts to load the ontology using OWL API. If the ontology is loaded, it is assumed that it is in a good format, although it may not be RDF/XML. For large ontologies, the ontology is a valid format (either RDF/XML or Turtle) if it can be [loaded with Jena](http://robot.obolibrary.org/query#executing-on-disk) to run the ROBOT report over. - -```python -import dash_utils -from dash_utils import format_msg - - -def is_common_format(ontology): - """Check FP 2 - Common Format. - - Args: - ontology (OWLOntology): ontology object - - Return: - PASS if OWLOntology is not None, ERROR otherwise. - """ - if ontology is None: - return {'status': 'ERROR', 'comment': 'Unable to load ontology'} - else: - return {'status': 'PASS'} - - -def big_is_common_format(good_format): - """Check FP 2 - Common Format on large ontologies - - Args: - good_format (bool): True if ontology could be parsed by Jena - - Return: - PASS if good_format, ERROR otherwise. - """ - if good_format is None: - return {'status': 'ERROR', - 'comment': 'Unable to load ontology (may be too large)'} - elif good_format is False: - return {'status': 'ERROR', - 'comment': 'Unable to parse ontology'} - else: - return {'status': 'PASS'} -``` diff --git a/principles/checks/fp_003.md b/principles/checks/fp_003.md deleted file mode 100644 index a3980d5..0000000 --- a/principles/checks/fp_003.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -layout: check -id: 3 -title: URI Automated Check ---- - -## [URI](http://obofoundry.org/principles/fp-003-uris.html) Automated Check - -Discussion on this check can be [found here](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/1017). - -### Requirements - -1. All entities in the ontology namespace **must** use an underscore to separate the namespace and local ID. -2. The local ID _should_ not be semantically significant, and _should_ be numeric. - -### Fixes - -Edit problematic IRIs to resolve the problems. [Click here](https://ontology101tutorial.readthedocs.io/en/latest/EntitiesTab.html#renaming-an-entity) for details on editing an IRI in Protégé. - -The full OBO Foundry ID Policy can be found [here](http://www.obofoundry.org/id-policy). In short, all IRIs should begin with your unique OBO Foundry namespace (e.g., `http://purl.obolibrary.org/obo/OBI_`). The local ID, which comes after the unique namespace, should be numeric (e.g., `http://purl.obolibrary.org/obo/OBI_0000001`). We recommend using seven digits. - -#### Updating an IRI - -1. Add an `owl:deprecated` annotation with a boolean value of `true` to the problematic term -2. Add `obsolete` to the beginning of the term's label to prevent duplicating labels -3. Create a new term with a valid IRI to replace this old term -4. Copy the old annotations (label, definition, etc., excluding the `owl:deprecated`) over to the new term -5. Add a [`IAO:0100001` (term replaced by)](http://purl.obolibrary.org/obo/IAO_0100001) annotation to the old term with a value of the new term's IRI - - Make sure this is an IRI annotation by selecting "IRI Editor" when adding the annotation in Protégé - -### Implementation - -All entity IRIs are retrieved from the ontology, excluding annotation properties. Annotation properties may use hashtags and words due to legacy OBO conversions for subset properties. All other IRIs are checked if they are in the ontology's namespace. If the IRI begins with the ontology namespace, the next character must be an underscore. If not, this is an error. The IRI is also compared to a regex pattern to check if the local ID after the underscore is numeric. If not, this is a warning. - -```python -import dash_utils -import os -import re - -from dash_utils import format_msg - -iri_pattern = r'http:\/\/purl\.obolibrary\.org\/obo\/%s_[0-9]{1,9}' -owl_deprecated = 'http://www.w3.org/2002/07/owl#deprecated' - -error_msg = '{0} invalid IRIs' -warn_msg = '{0} warnings on IRIs' - - -def has_valid_uris(robot_gateway, namespace, ontology): - """Check FP 3 - URIs. - - This check ensures that all ontology entities follow NS_LOCALID. - Annotation properties are not checked, as many are in legacy OBO format - and use #LOCALID. Obsolete entities are also ignored. LOCALID should - not be semantically meaningful, therefore numeric IDs should be used. - If the IRI start with the namespace, but does not use `_`, it will be - added to errors. If IRI starts with NS, uses _, but does not match the - IRI pattern with numbers, it will be added to warnings. - - Args: - robot_gateway (Gatway): - namespace (str): ontology ID - ontology (OWLOntology): ontology object - - Return: - INFO if ontology is None. ERROR if any errors, WARN if any warns, PASS - otherwise. - """ - if not ontology: - return {'status': 'ERROR', 'comment': 'Unable to load ontology'} - - entities = robot_gateway.OntologyHelper.getEntities(ontology) - error = [] - warn = [] - - for e in entities: - if e.isOWLAnnotationProperty(): - # allow legacy annotation properties - continue - - # check if the entity is obsolete - obsolete = False - for ann in ontology.getAnnotationAssertionAxioms(e.getIRI()): - if ann.getProperty().getIRI().toString() == owl_deprecated: - # check if the entity is obsolete - obsolete = dash_utils.is_obsolete(ann) - # if so, just ignore it - if obsolete: - continue - - iri = e.getIRI().toString().lower() - check = check_uri(namespace, iri) - if check == 'ERROR': - error.append(iri) - elif check == 'WARN': - warn.append(iri) - - return save_invalid_uris(namespace, error, warn) - - -def big_has_valid_uris(namespace, file): - """Check FP 3 - URIs on a big ontology. - - This check ensures that all ontology entities follow NS_LOCALID. - Annotation properties are not checked, as many are in legacy OBO format - and use #LOCALID. Obsolete entities are also ignored. LOCALID should - not be semantically meaningful, therefore numeric IDs should be used. - If the IRI start with the namespace, but does not use `_`, it will be - added to errors. If IRI starts with NS, uses _, but does not match the - IRI pattern with numbers, it will be added to warnings. - - Args: - namespace (str): ontology ID - file (str): path to ontology file - - Return: - INFO if ontology IRIs cannot be parsed. ERROR if any errors, WARN if - any warns, PASS otherwise. - """ - error = [] - warn = [] - - prefixes = True - header = True - valid = False - - # prefixes - owl = None - rdf = None - - with open(file, 'r') as f: - # TODO: rework to exclude deprecated classes - for line in f: - if 'Ontology' and 'about' in line: - if not owl and not rdf: - # did not find OWL and RDF - end now - return {'status': 'ERROR', - 'comment': 'Unable to parse ontology'} - - # end prefixes - prefixes = False - # valid ontology to parse (found Ontology declaration) - valid = True - - if line.strip().endswith('/>'): - # no ontology annotations - end header now - header = False - - elif prefixes and 'http://www.w3.org/2002/07/owl#' in line: - # set the OWL prefix - owl = dash_utils.get_prefix(line) - - elif prefixes and 'http://www.w3.org/1999/02/22-rdf-syntax-ns#'\ - in line: - # set the RDF prefix - rdf = dash_utils.get_prefix(line) - - elif header and ''.format(owl) in line: - # end of Ontology annotations = end of header - header = False - - elif not header and '{0}:about'.format(rdf) in line \ - and '{0}:AnnotationProperty'.format(owl) not in line: - # non-AP entity found - check the IRI - iri = dash_utils.get_resource_value(line).lower() - check = check_uri(namespace, iri) - if check == 'ERROR': - error.append(iri) - elif check == 'WARN': - warn.append(iri) - - if not valid: - # not valid ontology - return {'status': 'ERROR', - 'comment': 'Unable to parse ontology'} - - return save_invalid_uris(namespace, error, warn) - - -def check_uri(namespace, iri): - """Check if a given IRI is valid. - - Args: - namespace (str): ontology ID - iri (str): IRI to check - - Return: - ERROR, WARN, or True if passing. - """ - pattern = iri_pattern % namespace - if iri == 'http://purl.obolibrary.org/obo/{0}.owl'.format(namespace): - # ignore ontology IRI as it may be used in the ontology - return True - if iri.startswith(namespace): - # all NS IRIs must follow NS_ - if not iri.startwith(namespace + '_'): - return 'ERROR' - # it is recommended to follow NS_NUMID - elif not re.match(pattern, iri, re.IGNORECASE): - return 'WARN' - return True - - -def save_invalid_uris(ns, error, warn): - """Save invalid (error or warning) IRIs to a report file - (reports/dashboard/*/fp3.tsv). - - Args: - ns (str): ontology ID - error (list): list of ERROR IRIs - warn (list): list of WARN IRIs - - Return: - ERROR or WARN with detailed message, or PASS if no errors or warnings. - """ - if len(error) > 0 or len(warn) > 0: - file = 'build/dashboard/{0}/fp3.tsv'.format(ns) - with open(file, 'w+') as f: - for e in error: - f.write('ERROR\t{0}\n'.format(e)) - for w in warn: - f.write('WARN\t{0}\n'.format(w)) - - if len(error) > 0 and len(warn) > 0: - return {'status': 'ERROR', - 'file': 'fp3', - 'comment': ' '.join([error_msg.format(len(error)), - warn_msg.format(len(warn))])} - elif len(error) > 0: - return {'status': 'ERROR', - 'file': 'fp3', - 'comment': error_msg.format(len(error))} - elif len(warn) > 0: - return {'status': 'ERROR', - 'file': 'fp3', - 'comment': warn_msg.format(len(warn))} - return {'status': 'PASS'} -``` diff --git a/principles/checks/fp_004.md b/principles/checks/fp_004.md deleted file mode 100644 index 65a3e53..0000000 --- a/principles/checks/fp_004.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -layout: check -id: 4 -title: Versioning Automated Check ---- - -## [Versioning](http://obofoundry.org/principles/fp-004-versioning.html) Automated Check - -Discussion on this check can be [found here](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/1016). - -### Requirements - -1. The released ontology **must** have a version IRI. -2. The version IRI _should_ follow a dated format (`NS/YYYY-MM-DD/ontology.owl`) - -### Fixes - -First, make sure you have a valid version IRI pattern. See [Versioning Implementation](http://obofoundry.org/principles/fp-004-versioning.html#implementation) for more details. - -#### Adding a Version IRI in Protégé - -The "Ontology Version IRI" input is located in the "Active Ontology" tab that appears when you open your ontology in Protégé. - -#### Adding a Version IRI with ROBOT - -You may use the [ROBOT annotate](http://robot.obolibrary.org/annotate) command the add a version IRI. - -Please be aware that the [Ontology Development Kit](https://github.com/INCATools/ontology-development-kit) comes standard with a release process that will automatically generate a dated version IRI for your ontology release. - -### Implementation - -The version IRI is retrieved from the ontology using OWL API. For very large ontologies, the RDF/XML ontology header is parsed to find the owl:versionIRI declaration. If found, the IRI is compared to a regex pattern to determine if it is in date format. If it is not in date format, a warning is issued. If the version IRI is not present, this is an error. - -```python -import dash_utils -import re - -from dash_utils import format_msg - -# regex pattern to match dated version IRIs -pat = r'http:\/\/purl\.obolibrary\.org/obo/.*/([0-9]{4}-[0-9]{2}-[0-9]{2})/.*' - -# descriptions of issues -bad_format = 'Version IRI \'{0}\' is not in recommended format' -missing_version = 'Missing version IRI' - - -def has_versioning(ontology): - """Check fp 4 - versioning. - - Retrieve the version IRI from the OWLOntology object. If the version IRI - does not exist, ERROR. If the version IRI does exist, check if it is in the - recommended date format. If not, WARN. Otherwise PASS. - - Args: - ontology (OWLOntology): ontology object - - Return: - PASS, INFO, WARN, or ERROR with optional message - """ - if ontology is None: - return {'status': 'ERROR', 'comment': 'Unable to load ontology'} - - # retrieve version IRI or None from ontology - version_iri = dash_utils.get_version_iri(ontology) - if version_iri: - # compare version IRI to the regex pattern - search = re.search(pat, version_iri) - if search: - return {'status': 'PASS'} - else: - return {'status': 'WARN', - 'comment': bad_format.format(version_iri)} - else: - return {'status': 'ERROR', 'comment': missing_version} - - # TODO: check that versionIRI resolves - - -def big_has_versioning(file): - """Check fp 4 - versioning. - - This is suitible for large ontologies as it reads the file line by line, - instead of loading an OWLOntology object. This method looks for the - owl:versionIRI property in the header. - - Args: - file (str): path to ontology - - Return: - PASS, INFO, WARN, or FAIL with optional message - """ - # may return empty string if version IRI is missing - # or None if ontology cannot be parsed - version_iri = dash_utils.get_big_version_iri(file) - - if version_iri and version_iri != '': - # compare version IRI to the regex pattern - search = re.search(pat, version_iri) - if search: - return {'status': 'PASS'} - else: - return {'status': 'WARN', - 'comment': bad_format.format(version_iri)} - elif version_iri == '': - return {'status': 'ERROR', 'comment': missing_version} - else: - return {'status': 'ERROR', 'comment': 'Unable to parse ontology'} -``` diff --git a/principles/checks/fp_005.md b/principles/checks/fp_005.md deleted file mode 100644 index e9a79f0..0000000 --- a/principles/checks/fp_005.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -layout: check -id: 5 -title: Scope Automated Check ---- - -## [Scope](http://obofoundry.org/principles/fp-005-delineated-content.html) Automated Check - -Discussion on this check can be [found here](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/1015). - -### Requirements - -1. A scope ('domain') **must** be declared in the registry data - -### Fixes - -First, read the [FAQ](http://obofoundry.github.io/faq/how-do-i-edit-metadata.html) on how to edit the metadata for your ontology. Then, add the following to your [metadata file](https://github.com/OBOFoundry/OBOFoundry.github.io/tree/master/ontology) (replacing with your domain): - -``` -domain: experiments -``` - -### Implementation - -First, the registry data is checked for a 'domain' tag. If missing, that is an error. If it is present, the domain is compared to all other ontology domains. If the ontology shares a domain with one or more other ontologies, we return a list of those ontologies in an info message. - -```python -import dash_utils -from dash_utils import format_msg - -info_msg = 'Shares domain \'{0}\' with {1} other ontologies ({2})' - - -def has_scope(data, domain_map): - '''Check fp 5 - scope. - - Retrieve the "scope" tag from the data and compare to other scopes in the - map. If domains overlap, return INFO with a list of overlapping domains. - If scope is missing, ERROR. Otherwise, PASS. - - Args: - data (dict): ontology data from registry - domain_map (dict): map of ontology to domain - ''' - ns = data['id'] - if 'domain' in data: - domain = data['domain'] - else: - return {'status': 'ERROR', 'comment': 'Missing domain (scope)'} - - # This check is excluded for now - # exclude this NS from check (it will match itself) - # updated_domain_map = domain_map - # updated_domain_map.pop(ns) - # if domain in updated_domain_map.values(): - # same_domain = [] - # for ont_id, other_domain in domain_map.items(): - # if domain == other_domain: - # same_domain.append(ont_id) - # same_domain_str = ', '.join(same_domain) - # return {'status': 'INFO', - # 'comment': info_msg.format( - # domain, len(same_domain), same_domain_str)} - - return {'status': 'PASS'} -``` diff --git a/principles/checks/fp_006.md b/principles/checks/fp_006.md deleted file mode 100644 index a94871f..0000000 --- a/principles/checks/fp_006.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -layout: check -id: 6 -title: Textual Definitions Automated Check ---- - -## [Textual Definitions](http://obofoundry.org/principles/fp-006-textual-definitions.html) Automated Check - -Discussion on this check can be [found here](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/1010). - -### Requirements - -1. Each definition **must** be unique. -2. Each entity **must** not have more than one textual definition. -3. Each entity _should_ have a textual definition using [`IAO:0000115` (definition)](http://purl.obolibrary.org/obo/IAO_0000115). - -### Fixes - -#### Uniqueness - -Update each duplicate definition to have some detail that differentiates one term from another. - -#### Multiples - -If a term has more than one defintion, combine the two definitions. Alternatively, change one definition to an `rdfs:comment` if it just contains further details. - -#### Missing Definitions - -Add an [`IAO:0000115` (definition)](http://purl.obolibrary.org/obo/IAO_0000115) annotation to each term that is missing a definition. For help writing good definitions, see [Textual Definitions Recommendations](http://obofoundry.org/principles/fp-006-textual-definitions.html#recommendation). - -For adding defintions in bulk, check out [ROBOT template](http://robot.obolibrary.org/template). - -### Implementation - -[ROBOT report](http://robot.obolibrary.org/report) is run over the ontology. A count of violations for each of the following checks is retrieved from the report object: [duplicate definition](http://robot.obolibrary.org/report_queries/duplicate_definition), [multiple definitions](http://robot.obolibrary.org/report_queries/multiple_definitions), and [missing definition](http://robot.obolibrary.org/report_queries/missing_definition). If there are any duplicate or multiple defintions, it is an error. If there are missing definitions, it is a warning. - -```python -import dash_utils -from dash_utils import format_msg - - -def has_valid_definitions(report): - """Check fp 6 - textual definitions. - - If the ontology passes all ROBOT report definition checks, PASS. If there - are any violations, return that level of violation and a summary of the - violations. - - Args: - report (Report): ROBOT report object - """ - if report is None: - return {'status': 'INFO', - 'comment': 'ROBOT Report could not be generated'} - - # error level violations - duplicates = report.getViolationCount('duplicate_definition') - multiples = report.getViolationCount('multiple_definitions') - - # warn level violation - missing = report.getViolationCount('missing_definition') - - if duplicates > 0 and multiples > 0 and missing > 0: - return {'status': 'ERROR', - 'comment': ' '.join([duplicate_msg.format(duplicates), - multiple_msg.format(multiples), - missing_msg.format(missing), - help_msg])} - elif duplicates > 0 and multiples > 0: - return {'status': 'ERROR', - 'comment': ' '.join([duplicate_msg.format(duplicates), - multiple_msg.format(multiples), - help_msg])} - elif duplicates > 0 and missing > 0: - return {'status': 'ERROR', - 'comment': ' '.join([duplicate_msg.format(duplicates), - missing_msg.format(missing), - help_msg])} - elif multiples > 0 and missing > 0: - return {'status': 'ERROR', - 'comment': ' '.join([multiple_msg.format(multiples), - missing_msg.format(missing), - help_msg])} - elif duplicates > 0: - return {'status': 'ERROR', - 'comment': ' '.join([duplicate_msg.format(duplicates), - help_msg])} - elif multiples > 0: - return {'status': 'ERROR', - 'comment': ' '.join([multiple_msg.format(missing), - help_msg])} - elif missing > 0: - return {'status': 'WARN', - 'comment': ' '.join([missing_msg.format(missing), - help_msg])} - else: - # no violations found - return {'status': 'PASS'} - - -# violation messages -duplicate_msg = '{0} duplicate definitions.' -multiple_msg = '{0} multiple definitions.' -missing_msg = '{0} missing definitions.' -help_msg = 'See ROBOT Report for details.' -``` diff --git a/principles/checks/fp_007.md b/principles/checks/fp_007.md deleted file mode 100644 index 7b512d5..0000000 --- a/principles/checks/fp_007.md +++ /dev/null @@ -1,304 +0,0 @@ ---- -layout: check -id: fp_007 -title: Relations Automated Check ---- - -## [Relations](http://obofoundry.org/principles/fp-007-relations.html) Automated Check - -Discussion on this check can be [found here](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/981). - -### Requirements - -1. The ontology **must not** duplicate existing RO properties. -2. The ontology _should_ use existing RO properties, rather than creating new properties. - -### Fixes - -#### Duplicated Properties - -1. Add an `owl:deprecated` annotation with a boolean value of `true` to the problematic property in your ontology -2. Add `obsolete` to the beginning of the property's label -3. Replace all usages of that property with the duplicated RO property - -#### Non-RO Properties - -Review your non-RO properties to see if any can be replaced with an RO property using the steps above. Often, a corresponding property will not exist in RO and that is OK. - -### Implementation - -The object and data properties from the ontology are compared to existing RO properties. If any labels match existing RO properties, but do not use the correct RO IRI, this is an error. Any non-RO properties (no label match and do not use an RO IRI) will be listed as INFO messages. - -```python -import os -import unicodedata - -import dash_utils -from dash_utils import format_msg - -owl_deprecated = 'http://www.w3.org/2002/07/owl#deprecated' - -# Violation messages -ro_match = '{0} labels match RO labels.' -non_ro = '{0} non-RO properties used.' - - -def has_valid_relations(namespace, ontology, ro_props): - """Check fp 7 - relations. - - Retrieve all non-obsolete properties from the ontology. Compare their - labels and IRIs to the RO labels and IRIs. If a label matches an RO - property but does not match an RO IRI, return ERROR; RO properties should - not be duplicated. If a label matches neither an RO property or RO IRI, - return INFO; it is recommended to use RO properties, but not required. If - all properties used are RO properties, return PASS. - - Args: - namespace (str): ontology ID - ontology (OWLOntology): ontology object - ro_props (dict): map of RO property label to IRI - - Return: - PASS or violation level with optional help message - """ - if ontology is None: - return {'status': 'ERROR', 'comment': 'Unable to load ontology'} - - # ignore RO - if namespace == 'ro': - return {'status': 'PASS'} - - props = get_properties(namespace, ontology) - - # get results (PASS, INFO, or ERROR) - return check_properties(namespace, props, ro_props) - - -def get_properties(namespace, ontology): - """Create a map of normalized property label to property IRI. - - Args: - namespace (str): ontology ID - ontology (OWLOntology): ontology object - - Return: - Dict of label to property IRI - """ - props = {} - - # get object properties - for op in ontology.getObjectPropertiesInSignature(): - op_iri = op.getIRI() - obsolete = False - normal = None - for ann in ontology.getAnnotationAssertionAxioms(op_iri): - # find the label - ann_prop = ann.getProperty() - if ann_prop.isLabel(): - val = ann.getValue().asLiteral().orNull() - clz = val.getClass().getSimpleName().lower() - if clz == 'owlliteralimplstring': - # string datatype, get the literal value - normal = normalize_label(val.getLiteral()) - elif val is not None: - normal = normalize_label(val.toString()) - - elif ann_prop.getIRI().toString() == owl_deprecated: - # check if the property is obsolete - obsolete = dash_utils.is_obsolete(ann) - - if normal is not None and not obsolete: - props[normal] = op_iri.toString() - - # get data properties - for dp in ontology.getDataPropertiesInSignature(): - dp_iri = dp.getIRI() - obsolete = False - for ann in ontology.getAnnotationAssertionAxioms(op_iri): - ann_prop = ann.getProperty() - if ann_prop.isLabel(): - # find the label - val = ann.getValue().asLiteral().orNull() - clz = val.getClass().getSimpleName().lower() - if clz == 'owlliteralimplstring': - # string datatype, get the literal value - normal = normalize_label(val.getLiteral()) - elif val is not None: - normal = normalize_label(val.toString()) - - elif ann_prop.getIRI().toString() == owl_deprecated: - # check if the property is obsolete - obsolete = dash_utils.is_obsolete(ann) - - if normal is not None and not obsolete: - props[normal] = dp_iri.toString() - - return props - - -def big_has_valid_relations(namespace, file, ro_props): - """Check fp 7 - relations - on large ontologies. - - Retrieve all non-obsolete properties from the ontology. Compare their - labels and IRIs to the RO labels and IRIs. If a label matches an RO - property but does not match an RO IRI, return ERROR; RO properties should - not be duplicated. If a label matches neither an RO property or RO IRI, - return INFO; it is recommended to use RO properties, but not required. If - all properties used are RO properties, return PASS. - - Args: - namespace (str): ontology ID - file (str): path to ontology file - ro_props (dict): map of RO property label to IRI - - Return: - PASS or violation level with optional help message - """ - if not os.path.isfile(file): - return {'status': 'ERROR', 'comment': 'Unable to find ontology file'} - - # ignore RO - if namespace == 'ro': - return {'status': 'PASS'} - - props = big_get_properties(namespace, file) - - # get results (PASS, INFO, or ERROR) - return check_properties(namespace, props, ro_props) - - -def big_get_properties(namespace, file): - """Create a map of normalized property label to property IRI for large - ontologies by parsing RDF/XML. - - Args: - namespace (str): ontology ID - file (str): path to ontology file - - Return: - Dict of label to property IRI - """ - # TODO: handle different prefixes - props = {} - label = None - prefixes = True - with open(file, 'r') as f: - p_iri = None - for line in f: - if 'owl:ObjectProperty rdf:about' in line: - try: - p_iri = dash_utils.get_resource_value(line) - except Exception as e: - print('Unable to get IRI from line: ' + line) - elif p_iri and 'rdfs:label' in line: - label = None - try: - label = dash_utils.get_literal_value(line) - normal = normalize_label(label) - props[normal] = p_iri - except Exception as e: - # continue on to the next line - # might be a line break between (like RNAO) - print('Unable to get label from line: ' + line) - continue - elif p_iri and 'owl:ObjectProperty' in line: - p_iri = None - elif 'owl:Class' in line: - break - return props - - -def normalize_label(s): - """Clean and normalize a string label for comparison. - - Args: - s (str): label to normalize - - Return: - normalized string label - """ - clean = s.strip().lower().replace('"', '').replace('@en', '') - return unicodedata.normalize('NFC', clean) - - -def check_properties(namespace, props, ro_props): - """Compare the properties from an ontology to the RO properties. - - Args: - namespace (str): ontology ID - props (dict): map of ontology property label to IRI - ro_props (dict): map of RO property label to IRI - - Return: - PASS or violation level with optional help message - """ - # properties that share an RO label - # but have a different IRI - same_label = {} - - # properties that do not have an RO IRI - # and do not share a label with an RO prop - not_ro = {} - - for label, iri in props.items(): - label_match = False - iri_match = False - - if label in ro_props.keys(): - label_match = True - if iri in ro_props.values(): - iri_match = True - - if label_match and not iri_match: - ro_iri = ro_props[label] - if iri != ro_iri: - same_label[iri] = label - elif not label_match and not iri_match: - not_ro[iri] = label - - # delete the property map to free up memory - del props - - # maybe save a report file - if len(same_label) > 0 or len(not_ro) > 0: - save_invalid_relations(namespace, ro_props, same_label, not_ro) - - # return the results - if len(same_label) > 0 and len(not_ro) > 0: - return {'status': 'ERROR', - 'file': 'fp7', - 'comment': ' '.join([ro_match.format(len(same_label)), - non_ro.format(len(not_ro))])} - elif len(same_label) > 0 and len(not_ro) == 0: - return {'status': 'ERROR', - 'file': 'fp7', - 'comment': ro_match.format(len(same_label))} - elif len(not_ro) > 0 and len(same_label) == 0: - return {'status': 'INFO', - 'file': 'fp7', - 'comment': non_ro.format(len(not_ro))} - else: - return {'status': 'PASS'} - - -def save_invalid_relations(namespace, ro_props, same_label, not_ro): - """Save any violations to a TSV file in the reports directory. - - Args: - namespace (str): ontology ID - ro_props (dict): map of RO property label to IRI - same_label (dict): map of property label to IRI that matches RO - property label with a different IRI - not_ro (dict): map of property label to IRI that does not have an RO - IRI - """ - file = 'build/dashboard/{0}/fp7.tsv'.format(namespace) - with open(file, 'w+') as f: - f.write('IRI\tLabel\tIssue\n') - for iri, label in same_label.items(): - ro_iri = ro_props[label] - f.write('{0}\t{1}\tshares label with {2}\n'.format( - iri, label, ro_iri)) - for iri, label in not_ro.items(): - f.write('{0}\t{1}\tnot an RO property\n'.format(iri, label)) -``` diff --git a/principles/checks/fp_008.md b/principles/checks/fp_008.md deleted file mode 100644 index 93aa92e..0000000 --- a/principles/checks/fp_008.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -layout: check -id: 8 -title: Documentation Automated Check ---- - -## [Documentation](http://obofoundry.org/principles/fp-008-documented.html) Automated Check - -Discussion on this check can be [found here](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/1009). - -### Requirements - -1. The ontology **must** have a homepage. -2. The homepage URL **must** resolve. -3. The ontology **must** have a description. - -### Fixes - -First, read the [FAQ](http://obofoundry.github.io/faq/how-do-i-edit-metadata.html) on how to edit the metadata for your ontology. - -#### Adding or Updating a Homepage - -Add the following to your [metadata file](https://github.com/OBOFoundry/OBOFoundry.github.io/tree/master/ontology) (replacing with your homepage, which may just be your GitHub repository): - -``` -homepage: http://obi-ontology.org -``` - -If your homepage is not resolving, determine why (Is the server down? Is the URL wrong?) and update your homepage URL if needed. - -#### Adding a Description - -Add the following to your [metadata file](https://github.com/OBOFoundry/OBOFoundry.github.io/tree/master/ontology) (replacing with a short description about your ontology): - -``` -description: An integrated ontology for the description of life-science and clinical investigations -``` - -### Implementation - -The registry data is checked for 'homepage' and 'description' entries. If either is missing, this is an error. If the homepage is present, the URL is checked to see if it resolves (does not return an HTTP status of greater than 400). If the URL does not resolve, this is also an error. - -```python -import requests - - -def has_documentation(data): - """Check fp 8 - documentation. - - If the ontology has a valid homepage and description, return PASS. The - homepage URL must also resolve. - - Args: - data (dict): ontology registry data from YAML file - - Return: - PASS or ERROR with optional help message - """ - # check if the data exists - if 'homepage' in data: - home = data['homepage'] - else: - home = None - if 'description' in data: - descr = data['description'] - else: - descr = None - - if home is None and descr is None: - return {'status': 'ERROR', - 'comment': 'Missing homepage and description'} - elif home is None: - return {'status': 'ERROR', - 'comment': 'Missing homepage'} - elif descr is None: - return {'status': 'ERROR', - 'comment': 'Missing description'} - - # check if URL resolves - try: - request = requests.get(home) - except Exception as e: - return {'status': 'ERROR', - 'comment': 'homepage URL ({0}) does not resolve'.format(home)} - if request.status_code > 400: - return {'status': 'ERROR', - 'comment': 'homepage URL ({0}) does not resolve'.format(home)} - return {'status': 'PASS'} -``` diff --git a/principles/checks/fp_009.md b/principles/checks/fp_009.md deleted file mode 100644 index adfc5e9..0000000 --- a/principles/checks/fp_009.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -layout: check -id: 9 -title: Documented Plurality of Users Automated Check ---- - -## [Documented Plurality of Users](http://obofoundry.org/principles/fp-009-users.html) Automated Check - -Discussion on this check can be [found here](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/1008). - -### Requirements - -1. The ontology **must** have usages. - -### Fixes - -First, read the [FAQ](http://obofoundry.github.io/faq/how-do-i-edit-metadata.html) on how to edit the metadata for your ontology. - -#### Adding Usages - -Determine what other groups are using your ontology and how they are using it. Then, add the following to your [metadata file](https://github.com/OBOFoundry/OBOFoundry.github.io/tree/master/ontology) (replacing with the correct group name, link, and description): - -``` -usages: -- user: http://www.informatics.jax.org/disease (link to group) - description: MGI disease model annotations use DO (description of group) - examples: - - url: http://www.informatics.jax.org/disease/DOID:4123 (link to specific example) - description: Human genes and mouse homology associated with nail diseases (description of specific example) -``` - -You may have multiple exampels for each user, and mulitple users under the `usages` tag. - -### Implementation - -The registry data is checked for 'usage' entries. If they are missing, this is an error. - -```python -import dash_utils -from dash_utils import format_msg - - -def has_users(data): - """Check fp 9 - users. - If the ontology has an active issue tracker and examples of use, PASS. - - Args: - data (dict): ontology registry data from YAML file - - Return: - PASS or ERROR with optional help message - """ - if 'usages' in data: - usages = data['usages'] - # TODO: usages should have a valid user that resolves - # and a description - else: - usages = None - - if usages is None: - return {'status': 'ERROR', 'comment': 'Missing usages'} - return {'status': 'PASS'} -``` diff --git a/principles/checks/fp_011.md b/principles/checks/fp_011.md deleted file mode 100644 index 0f3eb8d..0000000 --- a/principles/checks/fp_011.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -layout: check -id: 11 -title: Locus of Authority Automated Check ---- - -## [Locus of Authority](http://obofoundry.org/principles/fp-011-locus-of-authority.html) Automated Check - -Discussion on this check can be [found here](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/1007). - -### Requirements - -1. The ontology **must** have a single contact person - -### Fixes - -First, read the [FAQ](http://obofoundry.github.io/faq/how-do-i-edit-metadata.html) on how to edit the metadata for your ontology. - -Next, determine who the point person for your ontology project is. This _must not_ be a mailing list. If this person does not already have a GitHub account, we request that they [create one](https://github.com/join). Then, add the following to your [metadata file](https://github.com/OBOFoundry/OBOFoundry.github.io/tree/master/ontology) (replacing with the correct email, name, and GitHub username): - -``` -contact: - email: foo@bar.com - label: John Smith - github: jsmith123 -``` - -### Implementation - -The registry data entry is validated with JSON schema using the [contact schema](https://raw.githubusercontent.com/OBOFoundry/OBOFoundry.github.io/master/util/schema/contact.json). The contact schema ensures that a contact entry is present and that the entry has a name and email address. - -```python -import jsonschema - -import dash_utils -from dash_utils import format_msg - -contact_schema = dash_utils.load_schema('dependencies/contact.json') - - -def has_contact(data): - """Check fp 11 - locus of authority. - - Check if the registry data contains a valid contract entry. - - Args: - data (dict): ontology registry data from YAML file - - Return: - PASS or ERROR with optional help message - """ - try: - jsonschema.validate(data, contact_schema) - except jsonschema.exceptions.ValidationError as ve: - if 'contact' in data: - # contact is in data but is not proper format - return {'status': 'ERROR', - 'comment': 'Invalid contact information'} - else: - # contact entry is missing from data - return {'status': 'ERROR', - 'comment': 'Missing contact information'} - return {'status': 'PASS'} -``` diff --git a/principles/checks/fp_012.md b/principles/checks/fp_012.md deleted file mode 100644 index 09ede31..0000000 --- a/principles/checks/fp_012.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -layout: check -id: 12 -title: Naming Conventions Automated Check ---- - -## [Naming Conventions](http://obofoundry.org/principles/fp-012-naming-conventions.html) Automated Check - -Discussion on this check can be [found here](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/1006). - -### Requirements - -1. Each label **must** be unique. -2. Each entity **must** not have more than one label. -3. Each entity _should_ have a label using `rdfs:label`. - -### Fixes - -#### Uniqueness - -Update at least one label to distinguish between the two terms. Add the original label to a `oboInOwl:hasExactSynonym` (alternatively, narrow, related, or broad) or [`IAO:0000118` (alternative term)](http://purl.obolibrary.org/obo/IAO_0000118) annotation. - -If the terms are exactly the same: - -1. Obsolete one of them by adding the `owl:deprecated` annotation property with a boolean value of `true` -2. Add `obsolete` to the beginning of this term's label -3. Add a [`IAO:0100001` (term replaced by)](http://purl.obolibrary.org/obo/IAO_0100001) annotation to this term pointing to the other, non-deprecated term. - - Make sure this is an IRI annotation by selecting "IRI Editor" when adding the annotation in Protégé - -#### Multiple Labels - -Determine which label most accurately describes the term. Change the other label(s) to `oboInOwl:hasExactSynonym` (alternatively, narrow, related, or broad) or [`IAO:0000118` (alternative term)](http://purl.obolibrary.org/obo/IAO_0000118). - -#### Missing Labels - -Add an `rdfs:label` annotation to each term that is missing a label. For adding labels in bulk, check out [ROBOT template](http://robot.obolibrary.org/template). - -### Implementation - -[ROBOT report](http://robot.obolibrary.org/report) is run over the ontology. A count of violations for each of the following checks is retrieved from the report object: [duplicate label](http://robot.obolibrary.org/report_queries/duplicate_label), [multiple labels](http://robot.obolibrary.org/report_queries/multiple_labels), and [missing label](http://robot.obolibrary.org/report_queries/missing_label). If there are any of these violations, it is an error. - -```python -import dash_utils -from dash_utils import format_msg - - -def has_valid_labels(report): - """Check fp 12 - naming conventions. - - If the ontology passes all ROBOT report label checks, return PASS. - - Args: - report (Report): complete ROBOT report - - Return: - PASS, INFO, or ERROR with optional help message - """ - if report is None: - return {'status': 'INFO', - 'comment': 'ROBOT Report could not be generated'} - - # all error level - duplicates = report.getViolationCount('duplicate_label') - missing = report.getViolationCount('missing_label') - multiples = report.getViolationCount('multiple_labels') - - if duplicates > 0 and multiples > 0 and missing > 0: - # all three violations - return {'status': 'ERROR', - 'comment': ' '.join([duplicate_msg.format(duplicates), - multiple_msg.format(multiples), - missing_msg.format(missing), - help_msg])} - elif duplicates > 0 and multiples > 0: - # duplicate and multiple labels - return {'status': 'ERROR', - 'comment': ' '.join([duplicate_msg.format(duplicates), - multiple_msg.format(multiples), - help_msg])} - elif duplicates > 0 and missing > 0: - # duplicate and missing labels - return {'status': 'ERROR', - 'comment': ' '.join([duplicate_msg.format(duplicates), - missing_msg.format(missing), - help_msg])} - elif multiples > 0 and missing > 0: - # multiple and missing labels - return {'status': 'ERROR', - 'comment': ' '.join([multiple_msg.format(multiples), - missing_msg.format(missing), - help_msg])} - elif duplicates > 0: - # just duplicate labels - return {'status': 'ERROR', - 'comment': ' '.join([duplicate_msg.format(duplicates), - help_msg])} - elif multiples > 0: - # just multiple labels - return {'status': 'ERROR', - 'comment': ' '.join([multiple_msg.format(multiples), - help_msg])} - elif missing > 0: - # just missing labels - return {'status': 'ERROR', - 'comment': ' '.join([missing_msg.format(missing), - help_msg])} - else: - # no label violations present - return {'status': 'PASS'} - - -# violation messages -duplicate_msg = '{0} duplicate labels.' -multiple_msg = '{0} multiple labels.' -missing_msg = '{0} missing labels.' -help_msg = 'See ROBOT Report for details.' -``` diff --git a/principles/checks/fp_016.md b/principles/checks/fp_016.md deleted file mode 100644 index 82689b2..0000000 --- a/principles/checks/fp_016.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -layout: check -id: 16 -title: Maintenance Automated Check ---- - -## [Maintenance](http://obofoundry.org/principles/fp-016-maintenance.html) Automated Check - -Discussion on this check can be [found here](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/1020). - -### Requirements - -1. The ontology _should_ be regularly updated. - -### Fixes - -Make sure all content in your ontology is up-to-date with scientific literature. If you make regular changes, make sure to have regular releases. - -### Implementation - -A version IRI is retrieved from the ontology, either using OWL API or parsing RDF/XML for large ontologies. This version IRI is checked against a regex pattern to determine if it is in date format. If so, the date is retrieved. If the last version IRI date is older than three years, this is an error. If it is older than two years, this is a warning. If it is older than one year, this will be an info message. - -```python -import datetime -import re - -import dash_utils -from dash_utils import format_msg - -# version IRI pattern -vpat = r'http:\/\/purl\.obolibrary\.org/obo/.*/([0-9]{4}-[0-9]{2}-[0-9]{2})/.*' - -# violation message -old_version_msg = 'last version ({0}) is over {1} year(s) old' - - -def is_maintained(ontology): - """Check fp 16 - maintenance. - - This method uses OWL API to retrieve the version IRI. - - Args: - ontology (OWLOntology): ontology object - - Return: - PASS, INFO, WARN, or ERROR with optional help message - """ - if ontology is None: - return {'status': 'ERROR', 'comment': 'Unable to load ontology'} - - version_iri = ontology.getOntologyID().getVersionIRI().orNull() - - if version_iri: - return check_version_iri(version_iri.toString()) - - # no version IRI (is Null) - return {'status': 'ERROR', 'comment': 'Missing version IRI to check date'} - - -def big_is_maintained(file): - """Check fp 16 - maintenance - on large ontologies. - - This is suitible for large ontologies as it reads the file line by line, - instead of loading an OWLOntology object. This method looks for the - owl:versionIRI property in the header. - - Args: - file (str): path to ontology file - - Return: - PASS, INFO, WARN, or ERROR with optional help message - """ - # may return empty string if version IRI is missing - # or None if ontology cannot be parsed - version_iri = dash_utils.get_big_version_iri(file) - - if version_iri and version_iri != '': - return check_version_iri(version_iri) - elif version_iri == '': - # no version IRI to check - return {'status': 'INFO', - 'comment': 'Missing version IRI to check date'} - else: - # ontology was in bad format - return {'status': 'INFO', 'comment': 'Unable to parse ontology'} - - -def check_version_iri(version_iri): - """Check if the version IRI is in date format then check when the version - IRI was last updated. - - Args: - version_iri (str): version IRI from ontology header - - Return: - PASS, INFO, WARN, or ERROR with optional help message - """ - # serach for date in version IRI using regex pattern - search = re.search(vpat, version_iri) - if search: - date = search.group(1) - splits = date.split('-') - version_date = datetime.datetime( - int(splits[0]), int(splits[1]), int(splits[2])) - - # check 3 years (error) - three_years_ago = datetime.datetime.now() \ - - datetime.timedelta(days=3*365) - if version_date < three_years_ago: - return {'status': 'ERROR', - 'comment': old_version_msg.format(date, 'three')} - - # check 2 years (warn) - two_years_ago = datetime.datetime.now() \ - - datetime.timedelta(days=2*365) - if version_date < two_years_ago: - return {'status': 'WARN', - 'comment': old_version_msg.format(date, 'two')} - - # check 1 year (info) - one_year_ago = datetime.datetime.now() - datetime.timedelta(days=365) - if version_date < one_year_ago: - return {'status': 'INFO', - 'comment': old_version_msg.format(date, 'one')} - - # has valid version IRI and it has been updated within the past year - return {'status': 'PASS'} - else: - # version IRI is not in the expected date format - return {'status': 'INFO', - 'comment': 'Version IRI does not have date information'} -``` diff --git a/principles/checks/fp_020.md b/principles/checks/fp_020.md deleted file mode 100644 index 64efa91..0000000 --- a/principles/checks/fp_020.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -layout: check -id: 20 -title: Responsiveness Automated Check ---- - -## [Responsiveness](http://obofoundry.org/principles/fp-020-responsiveness.html) Automated Check - -Discussion on this check can be [found here](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/959). - -### Requirements - -1. The ontology **must** have a tracker. - -### Fixes - -First, read the [FAQ](http://obofoundry.github.io/faq/how-do-i-edit-metadata.html) on how to edit the metadata for your ontology. - -#### Adding a Tracker - -If you do not already have a version control repository that has an [Issues Tracker](https://help.github.com/en/github/managing-your-work-on-github/about-issues), create one. We recommend creating a [GitHub Repository](https://help.github.com/en/github/getting-started-with-github/create-a-repo). To do this, you will need to [create a GitHub account](https://github.com/join) if you do not already have one. - -Once you have a version control repository, add the following to your [metadata file](https://github.com/OBOFoundry/OBOFoundry.github.io/tree/master/ontology) (replacing with the link to your repository's issue tracker): - -``` -tracker: https://github.com/DiseaseOntology/HumanDiseaseOntology/issues -``` - -### Implementation - -The registry data is checked for 'tracker' entry. If it is missing, this is an error. - -```python -import dash_utils -from dash_utils import format_msg - - -def is_responsive(data): - """Check fp 20 - responsiveness. - If the ontology has an active issue tracker, PASS. - - Args: - data (dict): ontology registry data from YAML file - - Return: - PASS or ERROR with optional help message - """ - if 'tracker' in data: - tracker = data['tracker'] - else: - tracker = None - - if tracker is None: - return {'status': 'ERROR', 'comment': 'Missing tracker'} - - return {'status': 'PASS'} -``` diff --git a/principles/fp-000-summary.md b/principles/fp-000-summary.md deleted file mode 100644 index 2de1a1d..0000000 --- a/principles/fp-000-summary.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -layout: principle -id: fp-000-summary -title: Overview ---- - -These principles are intended as normative for OBO Foundry ontologies, and ontologies submitted for review will be evaluated according to them. We consider these to be generally good practice, and recommend they be considered even if there are no plans to submit an ontology for review by the Foundry. Where we use capitalized words such as "MUST", and "SHOULD", they will be interpreted according to [RFC 2119: Key words for use in RFCs to Indicate Requirement Levels](https://www.ietf.org/rfc/rfc2119.html) when the principles are applied during reviews of ontologies for inclusion in the Foundry. - -There is currently an ongoing process to clarify the wording of the principles and expand on their purpose, implementation, and criteria to be used to evaluate ontologies for compliance with each principle. Please use the [issue tracker](https://github.com/OBOFoundry/OBOFoundry.github.io/issues) to let us know if there are further clarifications that you would like to see addressed for any of the principles. - -## Quick Summary - -The following summarizes each principle. See individual pages for details. - -P1) Open - The ontology MUST be openly available to be used by all without any constraint other than (a) its origin must be acknowledged and (b) it is not to be altered and subsequently redistributed in altered form under the original name or with the same identifiers. - -P2) Common Format - The ontology is made available in a common formal language in an accepted concrete syntax. - -P3) URI/Identifier Space - Each ontology MUST have a unique IRI in the form of an OBO Foundry permanent URL (PURL). - -P4) Versioning - The ontology provider has documented procedures for versioning the ontology, and different versions of ontology are marked, stored, and officially released. - -P5) Scope - The scope of an ontology is the extent of the domain or subject matter it intends to cover. The ontology must have a clearly specified scope and content that adheres to that scope. - -P6) Textual Definitions - The ontology has textual definitions for the majority of its classes and for top level terms in particular. - -P7) Relations - Relations should be reused from the Relations Ontology (RO). - -P8) Documentation - The owners of the ontology should strive to provide as much documentation as possible. - -P9) Documented Plurality of Users - The ontology developers should document that the ontology is used by multiple independent people or organizations. - -P10) Commitment To Collaboration - OBO Foundry ontology development, in common with many other standards-oriented scientific activities, should be carried out in a collaborative fashion. - -P11) Locus of Authority - There should be a person who is responsible for communications between the community and the ontology developers, for communicating with the Foundry on all Foundry-related matters, for mediating discussions involving maintenance in the light of scientific advance, and for ensuring that all user feedback is addressed. - -P12) Naming Conventions - The names (primary labels) for elements (classes, properties, etc.) in an ontology must be intelligible to scientists and amenable to natural language processing. Primary labels should be unique among OBO Library ontologies. - -P13) Notification of Changes - Ontologies SHOULD announce major changes to relevant stakeholders and collaborators ahead of release. - -P16) Maintenance - The ontology needs to reflect changes in scientific consensus to remain accurate over time. - -P20) Responsiveness - Ontology developers MUST offer channels for community participation and SHOULD be responsive to requests. diff --git a/principles/fp-001-open.md b/principles/fp-001-open.md deleted file mode 100644 index bc5f385..0000000 --- a/principles/fp-001-open.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -layout: principle -id: fp-001-open -title: Open (principle 1) ---- -GO TO: [Recommendations/Requirements](#recommendations-and-requirements) | [Implementation](#implementation) | [Examples/Counter‑Examples](#examples) | [Criteria for Review](#criteria-for-review) | [Feedback/Discussion](#feedback-and-discussion) - -## Summary - -The ontology MUST be openly available to be used by all without any constraint other than (a) its origin must be acknowledged and (b) it is not to be altered and subsequently redistributed in altered form under the original name or with the same identifiers. - -## Purpose - -OBO Foundry ontologies are resources for the entire biological and biomedical community. Furthermore, in order to realize the OBO Foundry vision of a suite of interoperable ontologies, ontology developers must be free to re-use terms from any OBO Foundry ontology. For these reasons, the ontologies must be available to all without any constraint on their use or redistribution. Nonetheless, it is proper that their original source is always credited and that after any external alterations, ontologies must never be redistributed under the same name or with the same identifiers. - -## Recommendations and Requirements - -### For ontology providers - -OBO Foundry Ontologies MUST EITHER be released under a [Creative Commons Attribution 3.0 Unported (CC BY 3.0)](https://creativecommons.org/licenses/by/3.0/) license or later (e.g. [Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/), OR released into the public domain under [Creative Commons CC0 1.0 Public Domain Dedication (CC0 1.0)](https://creativecommons.org/publicdomain/zero/1.0/). The license MUST be clearly stated using the http://purl.org/dc/terms/license property followed by the URL representing the license (e.g. https://creativecommons.org/licenses/by/3.0/) in the ontology file ([OWL example](https://github.com/INCATools/ontology-development-kit/blob/master/docs/License.md)). - -Note: CC-BY licenses allow others to distribute, remix, tweak, and build upon the work, even commercially, as long as they credit the creators for the original creation. CC0 specifies that the creators of an ontology waive, to the extent that they legally can be, all rights and place the ontology in the public domain. It does not prevent them from requesting that the ontology be properly credited and cited, but prevents any legal recourse if it is not credited. Many pros and cons of CC-BY versus CC0 are laid out in [this discussion](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/285). It is important to note that one can move from CC-BY to CC0 but not the other way around. - -### For ontology re-use - -1. The original source of an ontology must be credited according to the terms specified in the comment annotation of the ontology. - -2. Altered versions of an ontology that are not part of an official release (that is, by the ontology developers) must not be redistributed under the same name or with the same ontology IRI. - -3. If an individual term is reused without change to the definition, the original term IRI should be used. If the definition of a term (either text or logical) is changed, the original term IRI should not be reused. Suggestions for changes or improvements to term definitions should be submitted to the appropriate ontology issue tracker. - -4. Regardless of which license an ontology uses, we strongly request and recommend that any reuse of an ontology attributes the source in accordance with scientific norms and the [OBO Citation and Attribution Policy](http://www.obofoundry.org/docs/Citation). - -## Implementation - -### For ontology providers - -#### `.owl` files - -1. OBO Foundry Ontologies MUST specify the reuse constraints using the following annotations in any publically released OWL version of the ontology: - - 1. dcterms:license - specifies the license - see Example 1 (below) - 2. rdfs:comment - specifies terms of reuse - see Example 1 (below) - -2. OBO Foundry Ontologies that host terms developed by an external group (but which are not part of an existing ontology) must credit the external group - see Examples (below) - -3. See below under ontology re-use for guidelines on importing individual terms from external ontologies. - -#### `.obo` files - -1. OBO Foundry Ontologies must specify the reuse constraints using the following annotations in any publically released OBO version of the ontology: - 1. the license in a separate property annotation, which can be converted to a dc:license statement if the ontology is converted to OWL - see Example 2 (below) - 2. the reuse constraints using a comment in the official OBO version of the ontology - see Example 2 (below) - -### For ontology re-use - -#### Individual terms - -The attribution method for individual terms reused in another ontology (e.g., by MIREOT) is via use of their original IRI or ID - see Examples (below). - -1. **In OWL** - Any ontology re-using individual terms from another ontology should: - - 1. re-use the original term IRI (which for OBO Foundry ontologies is generally in the form of an OBO Foundry PURL) - 2. use an IAO:imported from annotation on each imported term to link back to the group (i.e. ontology) maintaining it, where more information would be available about the license - 3. include any annotations for term or definition editors from the original ontology - -2. **In OBO** - Any ontology re-using individual terms from another ontology should: - 1. re-use the original term ID (of the form ) - 2. include any XREFs to the original term editor(s) from the original ontology - -#### Full ontologies - -The attribution method for importing an entire ontology in OWL is simply to import the ontology without modification. - -3. The attribution method for using an ontology for an analysis is to cite the ontology as requested by the ontology developers. If the developers have not specified how to cite their ontology, use the ontology IRI, a publication if available, and the ontology website if available. - -## Examples - -NOTE: All examples are for illustration purposes and should not be considered valid ontology axioms. - -### Example 1: RDF-XML code for the license annotations: - -``` - - -"Ontology name" by "developer groups" is licensed -under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). - -"Ontology name" by developer groups is -licensed under CC BY 4.0. You are free to share (copy and redistribute -the material in any medium or format) and adapt (remix, transform, and -build upon the material) for any purpose, even commercially. for any -purpose, even commercially. The licensor cannot revoke these freedoms as -long as you follow the license terms. You must give appropriate credit -(by using the original ontology IRI for the whole ontology and original -term IRIs for individual terms), provide a link to the license, and -indicate if any changes were made. You may do so in any reasonable -manner, but not in any way that suggests the licensor endorses you or -your use. -``` - -The above comment for reuse conditions is for example only. Ontologies may use different wording appropriate to their own needs, as long as it is consistent with the license. - -### Example 2: Example of OBO code for the license annotation: - -``` -property_value: http://purl.org/dc/terms/license http://creativecommons.org/licenses/by/4.0/ - -remark: *Ontology name* by *developer group(s)* is licensed under CC BY 4.0. You - are free to share (copy and redistribute the material in any medium - or format) and adapt (remix, transform, and build upon the material) - for any purpose, even commercially. You must give appropriate credit - (by using the original ontology IRI for the whole ontology or - original term IRIs for individual terms), provide a link to the - license, and indicate if any changes were made. You may do so in any - reasonable manner, but not in any way that suggests the licensor - endorses you or your use. - -``` - -### Example 3: How to credit an external group for developing a term in your ontology. - -The first course of action should be to reuse the external term as is, by importing it with the original IRI (e.g. by MIREOT). At a minimum, the term definition should be imported, but there is still an open discussion about which other annotation need to be imported. - -Please see the discussion tab for additional discussion of how to use different annotation properties to credit external ontologies or definition sources. - -#### Example 3A: IAO:imported from - -The Ontology for Biomedical Investigation (OBI) imports the class "environmental material" from the Environment Ontology (ENVO), using OntoFox. The imported from axiom is automatically generated by Ontofox and added to "environmental material" in OBI: - -``` - - - - -environmental -material - - - -Material in or on which -organisms may live. - -environmental -material - - - - -``` - -## Counter-Examples - -- An ontology with no license statement is by default subject to the most restrictive copyright laws for those parts of the ontology that are copyrightable, and therefore is not useful within the OBO Foundry. -- CC BY-ND allows for redistribution, commercial and non-commercial, as long as it is passed along unchanged and in whole, with credit to the creators. This license is too restrictive for the OBO Foundry, because it requires that the ontology be re-used in its entirety, which prevents the re-use of individual terms. - -## Criteria for Review - -The ontology must have a license that is equivalent to or less restrictive than CC-BY, specified as described in the text and examples above. - -[This check is automatically validated.](checks/fp_001) The automatic check fully covers the requirements for this principle. - -## Feedback and Discussion - -To suggest revisions or begin a discussion pertaining to this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Editorial+WG,principles&title=Principle+%231+%22Open%22+%3CENTER+ISSUE+TITLE%3E). - -To suggest revisions or begin a discussion pertaining to the automated validation of this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Technical+WG,automated+validation+of+principles&title=Principle+%231+%22Open%22+-+automated+validation+%3CENTER+ISSUE+TITLE%3E). - -See also [this discussion of licensing](https://github.com/OBOFoundry/Operations-Committee/issues/103) by the OBO Foundry Operations Committee focusing on Creative Commons licenses. diff --git a/principles/fp-002-format.md b/principles/fp-002-format.md deleted file mode 100644 index 06b0be9..0000000 --- a/principles/fp-002-format.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -layout: principle -id: fp-002-format -title: Common Format (principle 2) ---- -GO TO: [Recommendations/Requirements](#recommendations-and-requirements) | [Implementation](#implementation) | [Examples/Counter‑Examples](#examples) | [Criteria for Review](#criteria-for-review) | [Feedback/Discussion](#feedback-and-discussion) - -## Summary - -The ontology is made available in a common formal language in an accepted concrete syntax. - -## Purpose - -A common format allows the maximum number of people to access and reuse an ontology. - -## Recommendations and Requirements - -All ontologies MUST have at least one OWL product whose name corresponds to the registered prefix (e.g., 'GO' --> go.owl, 'OBI' --> obi.owl). Thus the ontology whose IRI is http://purl.obolibrary.org/obo/ro.owl (known to the OBO Foundry as 'RO'), must have at least the product ro.owl. Developers are free to use whatever combination of technologies and formats is appropriate for development. However, the official OWL PURL (see [Principle 3](https://obofoundry.org/principles/fp-003-uris.html)) for the ontology MUST resolve to a syntactically valid OWL file using the [RDF-XML](https://www.w3.org/TR/rdf-syntax-grammar/) syntax. - -Developers can OPTIONALLY produce ontologies in other formats. These are conventionally the same IRI as the owl, but with .owl changed to the relevant extension (e.g., '.obo', '.json'). Note that such products are not listed by default. If you produce an additional format product, you should register it under the 'products' field in the appropriate metadata file found in this [folder](https://github.com/OBOFoundry/OBOFoundry.github.io/tree/master/ontology). - -## Implementation - -ROBOT offers functionality to convert a variety of formats, including OBO, to RDF/XML. Protégé allows you to save ontologies in RDF/XML, as well. The [Ontology 101 Tutorial](https://ontology101tutorial.readthedocs.io/en/latest/StartingProtege.html) has directions on starting and saving in Protégé. - -## Examples - -- The [Gene Ontology](http://geneontology.org) is maintained as OBO-Format. It is automatically converted to OWL and is available in both OBO and OWL via the OBO Foundry. - -- The [ChEBI ontology](https://www.ebi.ac.uk/chebi/) is maintained in a relational database using a custom schema, but makes an OBO-Format file available that is automatically converted to OWL. It is available in both OBO and OWL via the OBO Foundry. - -- [OBI](http://obi-ontology.org) is maintained as an OWL ontology. - -## Counter-Examples - -An ontology that is in Frames format, OWL/XML, or OWL Manchester Syntax. - -## Criteria for Review - -The ontology MUST be available in RDF/XML format. - -[This check is automatically validated.](checks/fp_002) The automatic check fully covers the requirements for this principle. - -## Feedback and Discussion - -To suggest revisions or begin a discussion pertaining to this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Editorial+WG,principles&title=Principle+%232+%22Format%22+%3CENTER+ISSUE+TITLE%3E). - -To suggest revisions or begin a discussion pertaining to the automated validation of this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Technical+WG,automated+validation+of+principles&title=Principle+%232+%22Format%22+-+automated+validation+%3CENTER+ISSUE+TITLE%3E). diff --git a/principles/fp-003-uris.md b/principles/fp-003-uris.md deleted file mode 100644 index 39ead91..0000000 --- a/principles/fp-003-uris.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -layout: principle -id: fp-003-uris -title: URI/Identifier Space (principle 3) ---- -GO TO: [Recommendations/Requirements](#recommendations-and-requirements) | [Implementation](#implementation) | [Examples/Counter‑Examples](#examples) | [Criteria for Review](#criteria-for-review) | [Feedback/Discussion](#feedback-and-discussion) - -## Summary - -Each ontology MUST have a unique IRI in the form of an OBO Foundry persistent URL (PURL) that includes the ontology's short namespace. - -## Purpose - -A unique namespace within the OBO Foundry Library allows the source of an element or term (e.g., class, property) from any ontology to be identified immediately by the prefix of the identifier. It also allows ontology element IRIs to be shortened to a compact URI or CURIE, which allows developers to use CURIES for working with ontologies. OWL syntax allows for ontologies and their elements to have identifiers in the form of an IRI. The OBO Foundry uses IRIs in the form of PURLs to allow an ontology and its elements to be resolvable (findable on the web). PURLs are URLs (and thus locate the resource) that are permanent or redirectable, allowing the URL to point to a new location when the resource moves. OBO Foundry PURLs use a standard format that includes the ontology namespace so that they can be easily maintained by a group of volunteers, and so ontology maintainers can update the location their PURL points to using a GitHub pull request. - -## Recommendations and Requirements - -Each ontology MUST have a unique IRI in the form of an OBO Foundry permanent URL (PURL). The PURL must include the ontology namespace, which is a short string of letters (usually 2-5) that represents the ontology. Namespaces MUST be approved by the OBO Foundry Operations Committee. Every element (class, property, etc.) created by the ontology MUST use the namespace in the identifier of each element, as specified in the OBO Foundry [ID policy](http://www.obofoundry.org/id-policy). - -## Implementation - -### Ontology Namespace: - -The ontology namespace MUST be unique; that is, it MUST NOT be in current use or have been used in the past. When used as part of the ontology IRI, the namespace is in lower case. When used as part of a CURIE, on its own, or as part of a term ID, the namespace MUST be capitalized (Note: this applies to ontologies submitted after 1st June 2024; mixed-case prefixes for ontologies submitted before this date may be retained). - -To request a new namespace, ontology developers MUST follow the guidelines outlined here. Note that very short namespaces (2-3 characters) are reserved for ontologies that cover a general domain and are likely to be frequently used. - -### Ontology IRI: - -The primary IRI for an OBO ontology IRI MUST have the following format: -https://purl.obolibrary.org/obo/$namespace.owl - -Note: To conform with OBO Foundry [Principle 2](https://obofoundry.org/principles/fp-002-format.html), the ontology IRI MUST resolve to the ontology file, not a landing page. - -For guidelines on how to create IRIs for ontology elements/terms, see the OBO Foundry [ID policy](http://www.obofoundry.org/id-policy). - -## Examples - -| Namespace | Ontology IRI | Term IRI | Term CURIE | -| ------------- | ------------- | ------------- | ------------- | -| GO | http://purl.obolibrary.org/obo/go.owl | http://purl.obolibrary.org/obo/GO_0008150 | GO:0008150 | -| PCO | http://purl.obolibrary.org/obo/pco.owl | http://purl.obolibrary.org/obo/PCO_0000000 | PCO:0000000 | - -## Counter Examples - -The following counter examples are valid ontology IRIs, but do not conform with OBO Foundry principles. - -- http://iridl.ldeo.columbia.edu/ontologies/SWEET.owl - -Furthermore, these IRIs do not resolve to the ontology file. - -- http://purl.org/dc/terms/ - -- http://dbpedia.org/ontology/ - -## Criteria for Review - -The ontology namespace MUST be registered following the procedures outlined within the [OBO Foundry membership requirements and technical details](http://www.obofoundry.org/docs/Policy_for_OBO_namespace_and_associated_PURL_requests.html) document. In addition, the ontology IRI MUST follow the format given above. - -[This check is automatically validated.](checks/fp_003) The automatic check fully covers the requirements for this principle. - -## Feedback and Discussion - -To suggest revisions or begin a discussion pertaining to this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Editorial+WG,principles&title=Principle+%233+%22URIs%22+%3CENTER+ISSUE+TITLE%3E). - -To suggest revisions or begin a discussion pertaining to the automated validation of this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Technical+WG,automated+validation+of+principles&title=Principle+%233+%22URIs%22+-+automated+validation+%3CENTER+ISSUE+TITLE%3E). - -See also [this discussion](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/2596) of URI capitalization by the OBO Foundry Operations Committee. diff --git a/principles/fp-004-versioning.md b/principles/fp-004-versioning.md deleted file mode 100644 index 14b82d1..0000000 --- a/principles/fp-004-versioning.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -layout: principle -id: fp-004-versioning -title: Versioning (principle 4) ---- -GO TO: [Recommendations/Requirements](#recommendations-and-requirements) | [Implementation](#implementation) | [Examples/Counter‑Examples](#examples) | [Criteria for Review](#criteria-for-review) | [Feedback/Discussion](#feedback-and-discussion) - -## Summary - -The ontology provider has documented procedures for versioning the ontology, and different versions of ontology are marked, stored, and officially released. - -## Purpose - -OBO projects share their ontologies using files in OWL or OBO format (see [Principle 2](https://obofoundry.org/principles/fp-002-format.html)). Ontologies are expected to change over time as they are developed and refined (see [Principle 16](https://obofoundry.org/principles/fp-016-maintenance.html)). This will lead to a series of different files. Consumers of ontologies must be able to specify exactly which ontology files they used to encode their data or build their applications, and be able to retrieve unaltered copies of those files in perpetuity. Note that this applies only to those versions which have been officially released. - -## Recommendations and Requirements - -In addition to an IRI specifying the current release (see [Principle 3](https://obofoundry.org/principles/fp-003-uris.html)), each official release MUST have a unique version IRI that resolves to the specific ontology artifact indicated. Consumers can then use the version IRI to uniquely identify which official release of the ontology they used, and to retrieve unaltered copies of the file(s). A _version IRI_ is a full path that MUST resolve to the particular version of the ontology artifact. Both the version IRI and the corresponding artifact MUST contain an identical _version identifier_ string. - -Version identifiers MUST either be of the form "YYYY-MM-DD" (that is, a date) OR use a numbering system (such as semantic versioning, i.e, of the form "NN.n"). Each version MUST associate with a distinct official release. The date versioning system is preferred, as it meshes with the requirement that version IRIs be specified using dated PURLs (see below). - -If a date-based version identifier is used, it MUST conform to [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html), ie. "YYYY-MM-DD". Variants of this--such as (a) using two digits for year instead of four (b) using one digit for month or year (c) using a delimiter other than a hyphen (d) any other ordering such as day/month/year or month/day/year (c) any other variant--MUST NOT be used. - -All OBO projects MUST also have versioned PURLs that resolve to the corresponding artifacts specified by the version IRIs, in perpetuity. If the files are moved, the PURL MUST be updated to resolve to the new location. - -Note that the content of official release files MUST NOT be changed. For example, if a bug is found in some official released file for some ontology, the bug MUST NOT be fixed by changing the file(s) for that official release. Instead the bug fixes should be included in a new official release, with new files, and consumers can switch to the new release. - -Additionally, each ontology SHOULD have an owl:versionInfo statement. When this is stated, it MUST correspond to the version Info. - -## Implementation - -See examples (below) for guidelines on how to specify the version within the ontology itself. If terms are imported from an external ontology, the “IAO:imported from” annotation (see [Principle 1](http://obofoundry.org/principles/fp-001-open.html)) may specify a dated version of the ontology from which they are imported. - -Regardless of the versioning system used for the ontology artifact, the version IRI SHOULD use an ISO-8601 dated PURL. In cases where there are multiple releases on the same day, the PURL points to the newest, and the previous release stays in the same folder or a subfolder, named in such a way as to distinguish the releases. Specifications for version IRIs are fully described in the OBO Foundry [ID policy](http://obofoundry.org/id-policy) document. In short: - -For a given version of an ontology, the ontology should be accessible at the following URL, where 'idspace' is replaced by the IDSPACE in lower case: - - OWL: http://purl.obolibrary.org/obo/idspace/YYYY-MM-DD/idspace.owl - OBO: http://purl.obolibrary.org/obo/idspace/YYYY-MM-DD/idspace.obo - -For example, for the version of OBI released 2009-11-06, the OWL document is accessible at http://purl.obolibrary.org/obo/obi/2009-11-06/obi.owl. - -An accepted alternative to the above scheme is to include /releases/ in the PURL, as follows: - - OWL: http://purl.obolibrary.org/obo/idspace/releases/YYYY-MM-DD/idspace.owl - OBO: http://purl.obolibrary.org/obo/idspace/releases/YYYY-MM-DD/idspace.obo - -## Examples - -For an OBO format ontology use the metadata tag: - - data-version: 2015-03-31 - data-version: 44.0 - -For an OWL format ontology, owl:versionInfo identifies the version and versionIRI identifies the resource: - - 2014-12-03 - - -CHEBI is an example of an OBO ontology that uses a non-date based system system for version identifier. An example versionIRI for CHEBI is http://purl.obolibrary.org/obo/chebi/187/chebi.owl. This corresponds to a value of `187` for `data-version` in OBO format. - -## Criteria for Review - -The released ontology MUST have a version IRI. The version IRI MUST use a date format (NS/YYYY-MM-DD/ontology.owl) OR use a semantic versioning format (e.g., NS/NN.n/ontology.owl). The version IRI MUST resolve to an ontology artifact that is associated with the same version identifier as used in the version IRI. - -[This check is automatically validated.](checks/fp_004) - -## Feedback and Discussion - -To suggest revisions or begin a discussion pertaining to this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Editorial+WG,principles&title=Principle+%234+%22Versioning%22+%3CENTER+ISSUE+TITLE%3E). - -To suggest revisions or begin a discussion pertaining to the automated validation of this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Technical+WG,automated+validation+of+principles&title=Principle+%234+%22Versioning%22+-+automated+validation+%3CENTER+ISSUE+TITLE%3E). diff --git a/principles/fp-005-delineated-content.md b/principles/fp-005-delineated-content.md deleted file mode 100644 index 5b48824..0000000 --- a/principles/fp-005-delineated-content.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -layout: principle -id: fp-005-delineated-content -title: Scope (principle 5) ---- - -## NOTE - -The wording of this principle is still in progress, with some issues still to be addressed (see Issues To Be Addressed below). - -## Summary - -The scope of an ontology is the extent of the domain or subject matter it intends to cover. The ontology must have a clearly specified scope and content that adheres to that scope. - -## Purpose - -An in-scope ontology prevents overlaps between ontologies (duplication of terms), facilitates user searches for specific content, and enables quick selection of ontologies of interest, yet still allows for new terms to be created via combination of existing terms (cross-products). - -## Recommendations and Requirements - -Ideally the scope should be fairly narrow. Required terms that are out of scope should be imported from the appropriate ontology unless no such ontology exists and there is an immediate need for an out-of-scope term (or set thereof). We encourage the ontology maintainers to create a shareable file with such terms so that the community can access, reuse, edit, and add these new terms as new ontologies with the intended scope are developed. - -## Implementation - -The domain (scope) covered by the ontology should be clearly stated. The statement should be brief and free of jargon; a few sentences should suffice. The content of the ontology should stay within the confines of the stated scope. Out-of-scope terms should be placed within a separate module that can be imported/exported as a single unit. -Generic terms must be maintained with community needs in mind. Mid/upper level terms should be considered for the [Core Ontology for Biology and Biomedicine (COB)](https://obofoundry.org/ontology/cob.html). - - -## Examples - -## Counter-Examples - -## Issues To Be Addressed (partial list): - -1.Would like a metadata tag in the ontology itself for this. TBD. - -2.Possible need for controlled vocabulary for scope/domain (for example: Anatomy, Upper Level Ontology, Disease, Phenotype, Applicable taxonomy) - -## Criteria for Review - -A scope (‘domain’) MUST be declared in the registry data, and terms from the ontology have to fall within that scope. - -[This check is automatically validated.](checks/fp_005) - -## Feedback and Discussion - -To suggest revisions or begin a discussion pertaining to this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Editorial+WG,principles&title=Principle+%235+%22Scope%22+%3CENTER+ISSUE+TITLE%3E). - -To suggest revisions or begin a discussion pertaining to the automated validation of this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Technical+WG,automated+validation+of+principles&title=Principle+%235+%22Scope%22+-+automated+validation+%3CENTER+ISSUE+TITLE%3E). diff --git a/principles/fp-006-textual-definitions.md b/principles/fp-006-textual-definitions.md deleted file mode 100644 index fd0f013..0000000 --- a/principles/fp-006-textual-definitions.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -layout: principle -id: fp-006-textual-definitions -title: Textual Definitions (principle 6) ---- -GO TO: [Recommendations/Requirements](#recommendations-and-requirements) | [Implementation](#implementation) | [Examples/Counter‑Examples](#examples) | [Criteria for Review](#criteria-for-review) | [Feedback/Discussion](#feedback-and-discussion) - -## Summary - -The ontology has textual definitions for the majority of its classes and for top level terms in particular. - -## Purpose - -A textual definition provides a human-readable understanding about what is a member of the associated class. Textual definitions are, optimally, in concordance with associated machine-readable logical definitions (the latter of which are OPTIONAL). - -## Recommendations and Requirements - -Textual definitions MUST be unique within an ontology (i.e. no two terms should share a definition) and be written in English. Textual definitions SHOULD follow Aristotelian form (e.g. “a B that Cs” where B is the parent and C is the differentia), where this is practical. - -For terms lacking textual definitions, there should be evidence of implementation of a strategy to provide definitions for all remaining undefined terms. In lieu of textual definitions, there can be elucidations when the term can not be rigorously defined. Note that textual definitions can be programmatically generated from logical definitions, if available (see [http://oro.open.ac.uk/21501/1/](http://oro.open.ac.uk/21501/1/)). In addition, [Dead Simple Ontology Design Patterns](https://github.com/INCATools/dead_simple_owl_design_patterns) (DOSDPs) can be used to generate both textual and logical definitions. DOSDPs are design specifications, written in YAML format, that specify structured text definitions and logical definitions for groups of ontology terms. These are widely used in many OBO Foundry ontologies, such as Mondo and uPheno. For some example patterns, see [Mondo patterns](https://mondo.readthedocs.io/en/latest/editors-guide/patterns/) and [uPheno patterns](https://github.com/obophenotype/upheno/tree/master/src/patterns/dosdp-patterns). - -Logical definitions, when present, should agree with textual definitions and vice versa. This is important for two reasons: (1) Reasoners classify terms solely based on logical definitions, while humans predominantly classify terms based on textual definitions, and mismatches between the two can cause unexpected misclassification; and (2) Curators could create incorrect annotations. An example of mismatched definitions: - -``` -http://purl.obolibrary.org/obo/OBI_0003243 blood assay datum - -Text definition: "A data item that is the specified output of a blood assay." -``` - -Logical definition (that does not match the textual def): -``` -= 'information content entity' and (is_specified_output_of some 'blood assay') -``` - -Logical definition (that matches the textual def): -``` -= 'data item' and (is_specified_output_of some 'blood assay') -``` - -While both logical definitions can be used to define the class, one better fits with the textual definition than the other. - -Note that it’s permissible to not to have a logical definition if the class is fuzzy or the axioms/relations can’t be composed equivalence axioms. - -Terms often benefit from examples of usage, as well as editor notes about edge cases and the history of the term, but these should be included as separate annotations and not in the definition. - -Instances, such as organizations or geographical locations, can benefit from definitions although it is understood that definitions for instances are not required. It is recognized that OBO format (e.g., versions 1.2 and 1.4) does not allow this as an option. - -## Implementation - -Textual definitions should be identified using the annotation property: ‘definition’ [http://purl.obolibrary.org/obo/IAO_0000115](http://purl.obolibrary.org/obo/IAO_0000115). The source of the definition should be provided using the annotation property ‘definition source’ [http://purl.obolibrary.org/obo/IAO_0000119](http://purl.obolibrary.org/obo/IAO_0000119), or as an axiom annotation on the definition assertion. - -An example of providing source in an axiom annotation: - -``` - rdf:type owl:Class ; - "Any complex formed of proteins that act in nucleotide-excision repair."@en ; - rdfs:label "nucleotide-excision repair complex"^^xsd:string . - -[ rdf:type owl:Axiom ; - owl:annotatedSource ; - owl:annotatedProperty ; - owl:annotatedTarget "Any complex formed of proteins that act in nucleotide-excision repair."@en ; - "PMID:10915862"^^xsd:string - ] . - -``` - -this corresponds to the obo format: - -``` -id: GO:0000109 -name: nucleotide-excision repair complex -def: "Any complex formed of proteins that act in nucleotide-excision repair." [PMID:10915862] -``` - -## Examples - -Class: primary phloem sieve element -
Term IRI: [http://purl.obolibrary.org/obo/PO_0025452](http://purl.obolibrary.org/obo/PO_0025452) -
Definition: A sieve element (PO:0025406) that is part of a portion of primary phloem (PO:0006075). -
Logical definition: - -``` -'sieve element' - and ('part of' some 'primary phloem') -``` - -Class: ecto-epithelial cell -
Term IRI: [http://purl.obolibrary.org/obo/CL_0002077](http://purl.obolibrary.org/obo/CL_0002077) -
Definition: An epithelial cell derived from ectoderm. -
Logical definition: - -``` -'epithelial cell' - and ('develops from' some 'ectodermal cell') -``` - -## Counter-Examples - -- No definition -- Circular/Self-referential definition - “A chromatography device is a device that uses chromatography” when chromatography is not defined elsewhere - -## Criteria for Review - -Each definition MUST be unique. Each entity MUST NOT have more than one textual definition (tagged using [IAO:0000115](http://purl.obolibrary.org/obo/IAO_0000115)). Textual definitions SHOULD be provided for most terms, and for top level terms especially. - -[This check is automatically validated.](checks/fp_006) - -## Feedback and Discussion - -To suggest revisions or begin a discussion pertaining to this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Editorial+WG,principles&title=Principle+%236+%22Definitions%22+%3CENTER+ISSUE+TITLE%3E). - -To suggest revisions or begin a discussion pertaining to the automated validation of this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Technical+WG,automated+validation+of+principles&title=Principle+%236+%22Definitions%22+-+automated+validation+%3CENTER+ISSUE+TITLE%3E). diff --git a/principles/fp-007-relations.md b/principles/fp-007-relations.md deleted file mode 100644 index a2b6338..0000000 --- a/principles/fp-007-relations.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -layout: principle -id: fp-007-relations -title: Relations (principle 7) ---- - -## NOTE - -The content of this page is scheduled to be reviewed. Improved wording will be posted as it becomes available. - -## Summary - -Relations should be reused from the Relations Ontology (RO). - -[This check is automatically validated.](checks/fp_007) - -## Purpose - -To facilitate interoperability between multiple ontologies, especially with respect to logical inference. That is, a reasoner can only detect logical inconsistencies between ontologies and infer new axioms if the ontologies use the same object properties. - -## Recommendations and Requirements - -Each OBO ontology MUST reuse existing relations (aka object properties) that have already been declared in the Relations Ontology (RO), -rather than declaring relations that mean the same as an existing RO relation. Where it makes sense for an ontology to declare a new relation in -its own ID space and there is a RO relation that is logically a super-property of the new relation, the new relation MUST be asserted to be -a sub-property of the RO relation. In such cases, it is requested that there still be coordination with RO, for example in the form of an issue -submitted to the [RO tracker](https://github.com/oborel/obo-relations/issues). - -## Implementation - -Reuse means that the actual relations PURLs are used. Ontology developers should be aware that RO relations (in rare instances) can evolve over time and previous relations might become obsolete. This means developers should monitor the state of the RO relations they use. - -## Examples - -## Counter-Examples - - diff --git a/principles/fp-008-documented.md b/principles/fp-008-documented.md deleted file mode 100644 index 461ca03..0000000 --- a/principles/fp-008-documented.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -layout: principle -id: fp-008-documented -title: Documentation (principle 8) ---- - -## NOTE - -The wording of this principle is still in progress, with some issues still to be addressed (see Issues To Be Addressed below). - -## Summary - -The owners of the ontology should strive to provide as much documentation as possible. The documentation should detail the different processes specific to an ontology life cycle and target various audiences (users or developers). - -[This check is automatically validated.](checks/fp_008) - -## Purpose - -Central to the issue of ontology documentation is ensuring transparency and traceability of artefact development. For each of the development steps, clear procedures should be made available. Documentation availability will be used to assess the quality of the resource. The following itemized list provides a core checklist, distinguishing general ontology documentation (general information about the resource) and local ontology documentation (documentation at artefact level itself and representational unit level (class and relations)). Documentation assessment with the purpose of assessing Ontology soundness, will cover updates and revision to the documentation. As ontology evolve, so should the documentation, for example by including a release documentation file. - -## Recommendations and Requirements - -## Implementation -### Term adoption -If a term that was previously defined in an identifier space belonging to ontology A (e.g. http://purl.obolibrary.org/obo/A_123) is adopted by ontology B (with a different identifier scheme, e.g. http://purl.obolibrary.org/obo/B_123) the following annotation assertion MUST be added to that term: - -OWL format (Turtle serialisation): -` rdfs:isDefinedBy ` - -OBO format: -`property_value: isDefinedBy http://purl.obolibrary.org/obo/b.owl` - -## Examples - -_Embedded or 'in-situ' documentation_: - Namely any specific metadata available from the ontology artefact itself providing information about the resource in its entirety or parts of it. - global ontology description (about the ontology as a whole): -- creator(s) -- maintainer(s) -- license -- version - -_local ontology documentation (about each term):_ - documentation for individual representational unit annotation -- justify the different elements of class metadata -- justify class axiomatization - documentation about the textual definition: is it manually created or generated with software assistance by relying on patterns and class axioms. - -_User documentation:_ - A documentation detailing the ontology's raison d'etre, its coverage, the use cases and query cases (including translation into SPARQL queries) it is intended to support - documentation about how to access the resource - documentation about how to produce semantic web document compatible with the representation intended by the developers (OWL examples, OWL coding patterns) -- availability of peer-reviewed publication about the resource -- availability of training material and tutorial -- availability of presentations (e.g. on slideshare) -- availability of web seminars (e.g. on a youtube channel) - -_Developer documentation:_ - -- documentation about collaborating and submitting issues by creating a [CONTRIBUTING.md file](http://mozillascience.github.io/working-open-workshop/contributing/) as described [here](http://obofoundry.org/principles/fp-020-responsiveness.html#implementation). -- documentation about authors contributions -- documentation about licensing terms, rights of use. -- documentation about version control -- documentation about release process -- documentation about changes in ontology between release version -- continuous integration -- documentation about the methodology used for developing the resource -- documentation about interaction with orthogonal resources -- documentation about resource acknowledgement -- documentation about term submission/term requests -- documentation about batch submission -- documentation about term deprecation and deprecation policy (aka retirement policy) -- documentation about conflict resolution -- a documentation detailing the use of software agent devised or exploited to develop, maintain, enhance, perform quality control and ensure high availability of the resource -- documentation about how the ontology is being used - -## Issues To Be Addressed (partial list): - -1. What minimal metadata is needed? - -2. What minimal documentation is needed? - -3. Clarification of the role of publications - -the ontology is well-documented (e.g. in a published paper describing the ontology or in manuals for developers and users) - - diff --git a/principles/fp-009-users.md b/principles/fp-009-users.md deleted file mode 100644 index 7088fde..0000000 --- a/principles/fp-009-users.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -layout: principle -id: fp-009-users -title: Documented Plurality of Users (principle 9) ---- -GO TO: [Recommendations/Requirements](#recommendations-and-requirements) | [Implementation](#implementation) | [Examples/Counter‑Examples](#examples) | [Criteria for Review](#criteria-for-review) | [Feedback/Discussion](#feedback-and-discussion) - -## Summary - -The ontology developers should document that the ontology is used by -multiple independent people or organizations. - -## Purpose - -This principle aims to ensure that the ontology tackles a relevant -scientific area and does so in a usable and sustainable fashion. - -## Recommendations and Requirements - -It is important to be able to illustrate usage outside of the immediate circle of ontology developers and stakeholders. Demonstrations of usage MUST be publicly available. Preferred indicators of usage are those that directly demonstrate such, including: - -- Use of the target ontology's term IRIs in an external ontology. Indicators of this type MUST include one or more IRIs for a term _within the external ontology_ that uses a term from the target ontology. - -- Documentation of requests from multiple users. Indicators of this type MUST link to specific requests in the issue tracker, OR link to an issue tracker search (for example, showing new term requests), OR link to an email thread or other mechanism _if publicly viewable_. - -- Publications showing the ontology being used in research by external users. Indicators of this type MUST provide citation details for the publications (link to PubMed or full text) and MUST include a sentence demonstrating the use (preferably taken from the title, abstract, or full text of the cited reference). Note that if citing full text that is behind a paywall, it may be necessary to provide a PDF for the paper. - -- Use of terms from the ontology to provide structure to or annotation of experimental or derived data. Indicators of this type MUST provide a link to a URL that shows the annotation or demonstrates the structure. - -- Terms imported into external ontologies. Indicators of this type MUST link to direct evidence of import, such as the OntoBee page for the term (which includes a section indicating which ontologies have imported it), OR to the OBO Dashboard page for the target ontology (which includes a section "Which ontologies use it?"), OR to any other source of direct evidence. A link to the importing ontology as a whole does not constitute appropriate evidence, as this is too indirect (that is, it requires extra steps to verify). - -- Inclusion of the target ontology on a documentation page that lists which resources are used for the project. Indicators of this type MUST include a link to the appropriate documentation page. - -Other indicators are currently possible as well: - -- Use in semantic web projects (e.g., Open PHACTS usage). - -- Use in software applications, including text mining or analysis pipelines. - -- Citations to the ontology publication(s); Note that such citations are only - relevant if the authors indicate actual use of the cited ontology - within some community (mere mention of the existence is not enough - to warrant inclusion). - -Note that the ontology can still be listed on the OBO Foundry website while publicising your resource in appropriate channels and searching for users with needs you can meet. - -## Implementation - -The ontology developers MUST provide links/citations to publicly available evidence of -use within your ontology [metadata file](https://github.com/OBOFoundry/OBOFoundry.github.io/tree/master/ontology) as given below (replacing with the correct group name, link, and description): - -```yaml -usages: -- user: http://www.informatics.jax.org/disease (link to group) - description: MGI disease model annotations use DO (description of group) - examples: - - url: http://www.informatics.jax.org/disease/DOID:4123 (link to specific example) - description: Human genes and mouse homology associated with nail diseases (description of specific example) -``` - -You may have multiple examples for each user, and mulitple users under the `usages` tag. - -## Examples - -Use of PSI-MOD term IRI (in the form of a CURIE) in the PR ontology: -```yaml -- user: http://purl.obolibrary.org/obo/pr - description: Protein Ontology - examples: - - url: https://proconsortium.org/app/export/obo/PR:000027653/ - description: OBO Format stanza showing use of PSI-MOD term in logical definition -``` -Term requests to PR from multiple users: -```yaml -- user: (multiple) - description: Term requests made via the Protein Ontology GitHub tracker - examples: - - url: https://github.com/PROconsortium/PRoteinOntology/issues?q=is%3Aissue+label%3A%22Term+Request%22 - description: List of issues tagged with 'Term Request' to PRO -``` -Publication showing the Disease Ontology being used in research by external users -```yaml -- user: https://pubmed.ncbi.nlm.nih.gov/36860337/ - description: Machine learning-based prediction of candidate gene biomarkers correlated with immune infiltration in patients with idiopathic pulmonary fibrosis - examples: - - url: https://pubmed.ncbi.nlm.nih.gov/36860337/ - description: In abstract, "Functional annotation, pathway enrichment, Disease Ontology and gene set enrichment analyses revealed..." -``` -Use of terms from GO for annotation: -```yaml -- user: https://www.uniprot.org - description: UniProt - examples: - - url: https://www.uniprot.org/uniprotkb/Q15796/entry#function - description: Functional annotation using GO (see subsection entitled "GO annotations") -``` -OBI terms imported into external ontologies -```yaml -- user: (multiple) - description: Ontologies using OBI terms - examples: - - url: http://dashboard.obofoundry.org/dashboard/obi/dashboard.html - description: List of ontologies using at least one OBI term (See section entitled "Info: Which ontologies use it?") - - url: https://ontobee.org/ontology/OBI?iri=http://purl.obolibrary.org/obo/OBI_0000691 - description: List of ontologies using the term 'ABI 377 automated sequencer' (See section entitled "Ontologies that use the Class") -``` - -## Counter-Examples - -- Mere mention of the existence of an ontology in a publication is not -enough to count as evidence of usage - -- Reference to any evidence that cannot be viewed publicly - -## Criteria for Review - -Ontology developers must demonstrate at least three external users specified within the metadata file. External users are defined either as researchers not -significantly overlapping in personnel with the developers or three independent groups with three independent artefacts (db, etc) that use -the ontology. Note that new ontologies are not expected to have a plurality of users, and thus the automatic evaluation of this criterion can be ignored. - -[This check is automatically validated.](checks/fp_009) - -## Feedback and Discussion - -To suggest revisions or begin a discussion pertaining to this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Editorial+WG,principles&title=Principle+%239+%22Users%22+%3CENTER+ISSUE+TITLE%3E). - -To suggest revisions or begin a discussion pertaining to the automated validation of this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Technical+WG,automated+validation+of+principles&title=Principle+%239+%22Users%22+-+automated+validation+%3CENTER+ISSUE+TITLE%3E). diff --git a/principles/fp-010-collaboration.md b/principles/fp-010-collaboration.md deleted file mode 100644 index 6cf2412..0000000 --- a/principles/fp-010-collaboration.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -layout: principle -id: fp-010-collaboration -title: Commitment To Collaboration (principle 10) ---- - -## Summary - -OBO Foundry ontology development, in common with many other standards-oriented scientific -activities, should be carried out in a collaborative fashion. - -## Purpose - -The benefits of collaboration are threefold: (1) Avoid duplication of work; (2) Increase interoperability; and (3) Ensure that ontology content is both scientifically sound and meets community needs. - -## Implementation - -### Recommendation: - -It is expected that Foundry ontologies will collaborate with other Foundry ontologies, particularly in ensuring orthogonality of distinct ontologies, in re-using content from other ontologies in cross-product definitions where appropriate, and in establishing and evolving Foundry principles to advance the Foundry suite of ontologies to better serve the joint users. Where there are multiple ontology providers in a particular domain, they are particularly encouraged to get together and determine how the domain should be divided between the ontologies, or whether the ontologies should be merged into a single artifact. Should it be determined that there is a competing ontology in the same domain, the Foundry ontology should invite the developers of the external ontology to collaborate and should strive to negotiate an arrangement that is beneficial to both projects. If necessary, conflicts can be mediated in dedicated workshops or using the [obo-discuss mailing list](https://groups.google.com/forum/#!forum/obo-discuss) where Foundry advisors and members of the editorial board can help the parties negotiate to a mutually agreeable solution. - -### Examples: - -- _Collaborative workshop_: http://ncorwiki.buffalo.edu/index.php/Protein_Ontology_Workshop -- _Conflict resolution_: The Statistical Methods Ontology (STATO) and Ontology of Biological and Clinical Statistics (OBCS) both cover statistics. The developers of each have posted to the OBO Foundry discussion list to work out how to collaborate. -- _Contribution to external ontology_: Plant Ontology (PO) curators contribute definitions to Gene Ontology (GO) for biological processes and cell components in plants. PO then uses the GO terms in their definition of corresponding structures and stages. -- _Documentation of collaboration_: Cell Line Ontology (CLO), Cell Ontology (CL), and Ontology of Biomedical Investigations (OBI) published a paper sorting out their overlap and documented working together. Sarntivjiai et al., "CLO: The cell line ontology", J. Biomed. Sem., 2014, 5, 37. http://www.ncbi.nlm.nih.gov/pubmed/25852852 -- _Providing terms upon request_: The Disease Ontology (DO) responded to a request from the PRotein Ontology for curation of certain disease terms. -- _Providing guidance on how to contribute_: The Relations Ontology (RO) GitHub includes a [CONTRIBUTING.md](https://github.com/oborel/obo-relations/blob/master/CONTRIBUTING.md) file. - -### Counter-examples: - -Interactions between ontologies developed by the same entity (person, consortium) are not evidence of collaboration. - -## Criteria for Review - -Ontology developers must document their attempts at an open dialog with OBO Foundry members, for example by attempting to ascertain if there are other possible ontologies in (or overlapping) the domain of interest. Such documentation can be a simple pointer to an e-mail thread on the OBO discuss list. If there are other ontologies that might need to be aligned or have boundaries determined, evidence of coordination or cooperation should be provided. Further evidence of collaboration may include examples of terms that have been provided to other ontologies in the OBO Foundry community, while evidence for a willingness to collaborate includes the creation of a CONTRIBUTING.md file to provide guidance for contributions ([learn more](http://mozillascience.github.io/working-open-workshop/contributing/)). Finally, hosting or participating in collaborative workshops or meetings attended by OBO Foundry community members is considered evidence of collaboration. - -## Feedback and Discussion - -To suggest revisions or begin a discussion pertaining to this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Editorial+WG,principles&title=Principle+%2310+%22Collaboration%22+%3CENTER+ISSUE+TITLE%3E). - -To suggest revisions or begin a discussion pertaining to the automated validation of this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Technical+WG,automated+validation+of+principles&title=Principle+%2310+%22Collaboration%22+-+automated+validation+%3CENTER+ISSUE+TITLE%3E). diff --git a/principles/fp-011-locus-of-authority.md b/principles/fp-011-locus-of-authority.md deleted file mode 100644 index a1e3d01..0000000 --- a/principles/fp-011-locus-of-authority.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -layout: principle -id: fp-011-locus-of-authority -title: Locus of Authority (principle 11) ---- -GO TO: [Recommendations/Requirements](#recommendations-and-requirements) | [Implementation](#implementation) | [Examples/Counter‑Examples](#examples) | [Criteria for Review](#criteria-for-review) | [Feedback/Discussion](#feedback-and-discussion) - -## Summary - -There should be a person who is responsible for communications between the -community and the ontology developers, for communicating with the Foundry on all -Foundry-related matters, for mediating discussions involving maintenance in the -light of scientific advance, and for ensuring that all user feedback is addressed. - -## Purpose - -It is important that there is a person responsible for communication rather than a group of people or a list. Often in communications to a list, the responsibility for responding can be diffused and it is likely that in some scenarios no response will be given. It may also, from time to time, be necessary to engage in strategic communications (e.g. relating to funding or collaboration possibilities) that are not able to be made public, and these should not be conducted on public mailing lists. The designation of a contact person is not to be interpreted as a designation for credit. Note that alternative contacts can be designated in case the primary contact is unavailable. However, as for the primary contact, each alternative contact must be an individual. - -## Recommendations and Requirements - -A primary contact person MUST be assigned. -The name, email address and GitHub username of the contact person MUST be provided when requesting to register with [OBO](http://obofoundry.org). The contact person MUST be subscribed to obo-discuss in order to be kept abreast of community developments of relevance to -participating ontology projects, but the primary contact person can, of course, delegate -these responsibilities for the project as necessary. The email address of the person who is the locus of the -authority MUST be kept up-to-date, and before that person ceases to have responsibility -for the project, they should identify a replacement and update the metadata accordingly -(via the [OBO Foundry issue tracker](https://github.com/OBOFoundry/OBOFoundry.github.io/issues)) before they move on. - -## Implementation - -First, read the [FAQ](http://obofoundry.github.io/faq/how-do-i-edit-metadata.html) on how to edit the metadata for your ontology. - -The contact email MUST NOT be a mailing list. The GitHub account MUST be for the individual designated as the locus of authority. If this person does not already have a GitHub account, we request that they [create one](https://github.com/join). Then, add the following to your [metadata file](https://github.com/OBOFoundry/OBOFoundry.github.io/tree/master/ontology) (replacing with the correct email, name, and GitHub username): - -`contact: email: foo@bar.com label: John Smith github: jsmith123` - -## Examples: - -For Mondo, the primary contact person is Nicole Vasilevsky (nicole {at} tislab.org) and her GitHub handle is: nicolevasilevsky. - -## Counter-Examples: - -Mailing list; for ChEBI, chebi-help@ebi.ac.uk - -## Criteria for Review - -Email address will be checked to ensure it is for an individual and that it is written in a standard format. - -[This check is automatically validated.](checks/fp_011) - -## Feedback and Discussion - -To suggest revisions or begin a discussion pertaining to this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Editorial+WG,principles&title=Principle+%2311+%22Contact%22+%3CENTER+ISSUE+TITLE%3E). - -To suggest revisions or begin a discussion pertaining to the automated validation of this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Technical+WG,automated+validation+of+principles&title=Principle+%2311+%22Contact%22+-+automated+validation+%3CENTER+ISSUE+TITLE%3E). diff --git a/principles/fp-012-naming-conventions.md b/principles/fp-012-naming-conventions.md deleted file mode 100644 index d0eb66f..0000000 --- a/principles/fp-012-naming-conventions.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -layout: principle -id: fp-012-naming-conventions -title: Naming Conventions (principle 12) ---- - -## NOTE - -The content of this page is scheduled to be reviewed. Improved wording will be posted as it becomes available. - -## Details - -For full details, see this paper: - -Briefly, some important things to remember: - -- use rdfs:label for the primary label -- include exactly one rdfs:label for every declared entity (e.g. class, property) -- write labels, synonyms, etc as if writing in plain English text. ie use spaces to separate words, only capitalize proper names (e.g. Parkinson disease). Do not use CamelCase, do_not_use_underscores -- avoid extra spaces between words, or at the beginning or end of the term label -- spell out abbreviations. Abbreviations can be included as a separate property. -- make the primary labels to be as unambiguous as possible. Remember, your ontology may be used in a different context than that for which it was originally intended. Remember also of course that the label should be unambiguous without looking at parent terms -- labels should be unique within an ontology -- use the IAO property 'obo foundry unique label' [http://purl.obolibrary.org/obo/IAO_0000589](http://purl.obolibrary.org/obo/IAO_0000589) to declare a pan-OBO unique label if required - -[This check is automatically validated.](checks/fp_012) - -## Examples - -## Counter-Examples - - diff --git a/principles/fp-013-notification.md b/principles/fp-013-notification.md deleted file mode 100644 index def8dcb..0000000 --- a/principles/fp-013-notification.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -layout: principle -id: fp-013-notification -title: Notification of Changes (principle 13) ---- - -GO TO: [Recommendations/Requirements](#recommendations-and-requirements) | [Implementation](#implementation) | [Examples/Counter‑Examples](#examples) | [Criteria for Review](#criteria-for-review) | [Feedback/Discussion](#feedback-and-discussion) - -Summary -------- - -Ontologies SHOULD announce major changes to relevant stakeholders and collaborators ahead of release. - -Purpose -------- - -To maintain the reliability of an ontology for stakeholders, advance announcement of upcoming changes--as -opposed to giving after-the-fact notice (or none at all)--is crucial. Such announcement will provide stakeholders an opportunity for input on upcoming changes, -and will allow updates to any dependencies (e.g., terms, annotations, ontologies) affected by those changes. - -Recommendations and Requirements -------- -Ontology owners SHOULD, in accordance with this principle, pre-announce changes to a primary group of users who actively monitor the ontology and its changes, for example, via a mailing list (ontology-specific or more general, as deemed suitable), a social media group (relevant to the ontology), or via announcements on a home page or elsewhere. The lead time for announcements can be determined according to release lifecycles of major ontology applications and is expected to vary by domain. - -The kinds of changes that might warrant a pre-announcement include (but are not limited to): -- Planned obsoletions. Terms that will be made obsolete. Such announcements can provide users the opportunity to intervene if necessary. -- Major hierarchy rearrangements. Moving branches from one point in the hierarchy to another, especially large branches affecting many terms or those close to the top of the hierarchy. - -Term additions and small hierarchy changes are not expected to need pre-announcement but doing so is not prohibited. - -Implementation --------------- - -The need for notification of changes--and the time frame in which notifications are made--should be based on the granularity of the changes and their potential impact -(for example, changes to low-level terms are likely not as impactful as those to high-level terms). Types of changes that might benefit from notification include term -obsoletions, term modifications, new terms, and any others that are determined with stakeholder benefit in mind. Announcments can be concise or verbose, and -SHOULD be made a minimum of 7 days in advance of the release in which the changes take effect. - -The following are possible avenues for notification: -* Submission of a GitHub ticket announcing the change -* Announcement made via social media (Twitter, Facebook, Slack, etc) -* Announcement made via general or ontology-specific mailing list -* Announcement of pending changes made as a GitHub pre-release -* Change log or release note, if published in advance - -It is expected that announcements include links to where discussions or questions can be directed. - -Examples --------- - -- GitHub issue: https://github.com/geneontology/go-announcements/issues/275 -- Social media (Twitter): https://twitter.com/diseaseontology/status/1301907848625033216 -- Mailing list announcement (general): https://groups.google.com/g/obo-discuss/c/RrCF5f9FRC4/m/nEVwLqN5CQAJ -- Mailing list announcement (ontology-specific): https://groups.google.com/g/obi-users/c/wweskCfHbSc -- GitHub pre-release: https://github.com/obi-ontology/obi/pull/1558 -- Advance release note: https://proconsortium.org/download/release_55.0/pro_release_note.txt - -Counter-Examples ----------------- - -The following mechanisms, while useful, do not fulfill the recommendations herein since they occur concurrently with the changes of interest: - -- Announcement of changes in a release note when that note is for the same release as that in which the change first appears -- A change log that is not published in advance - -Criteria for Review -------------------- - -Notification of changes SHOULD be published prior to a new release version of the Ontology. The period between publishing the changes -and the release date must be no less than 7 days but can be longer (based upon agreement between ontology developers and users). - -## Feedback and Discussion - -To suggest revisions or begin a discussion pertaining to this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Editorial+WG,principles&title=Principle+%2313+%22Notification%22+%3CENTER+ISSUE+TITLE%3E). - -To suggest revisions or begin a discussion pertaining to the automated validation of this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Technical+WG,automated+validation+of+principles&title=Principle+%2313+%22Notification%22+-+automated+validation+%3CENTER+ISSUE+TITLE%3E). - diff --git a/principles/fp-016-maintenance.md b/principles/fp-016-maintenance.md deleted file mode 100644 index b526101..0000000 --- a/principles/fp-016-maintenance.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -layout: principle -id: fp-016-maintenance -title: Maintenance (principle 16) ---- - -## NOTE - -The wording of this principle is still in progress. - -## Summary and Purpose - -The ontology needs to reflect changes in scientific consensus to remain accurate over time. - -[This check is automatically validated.](checks/fp_016) - -## Implementation - -Ideally, the maintainer of an ontology SHOULD actively monitor for any changes in scientific consensus, but--at a minimum--the maintainer MUST respond to requests from the community pointing out such changes in accordance with the [Responsiveness principle](http://obofoundry.org/principles/fp-020-responsiveness.html). Tentatively, we consider scientific consensus to be reached if multiple publications by independent labs over a year come to the same conclusion, and there is no or limited (<10%) dissenting opinions published in the same time frame. In cases when an area remains controversial, and no consensus is reached, then it is up to the ontology maintainer to either leave out the controversial term, or pick a viewpoint for practical considerations, and note the presence of controversy in an editor note. - -## Examples - -## Counter-Examples - -## Criteria for Review - -The developers of the ontology need to include a statement specifying how they are planning to maintain the ontology. We expect that an ontology will be maintained for at least 3 years from the time of acceptance. - - diff --git a/principles/fp-020-responsiveness.md b/principles/fp-020-responsiveness.md deleted file mode 100644 index b2ec8ac..0000000 --- a/principles/fp-020-responsiveness.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -layout: principle -id: fp-020-responsiveness -title: Responsiveness (principle 20) ---- -GO TO: [Recommendations/Requirements](#recommendations-and-requirements) | [Implementation](#implementation) | [Examples/Counter‑Examples](#examples) | [Criteria for Review](#criteria-for-review) | [Feedback/Discussion](#feedback-and-discussion) - -## Summary - -Ontology developers MUST offer channels for community participation and SHOULD be responsive to requests. - -## Purpose - -Ontology development benefits from community input, which is strongly encouraged by the OBO Foundry. Accordingly, "responsiveness" is a key quality of our general collaborative spirit. This principle is intended to ensure that channels for community input are available and that responses to input are given swiftly. - -## Recommendations and Requirements - -Ontology developers MUST set up a public mechanism to track community requests and suggestions (collectively, “issues”), and SHOULD aim to respond within 2-5 working days. To facilitate submission of well-crafted issues, ontology developers SHOULD create a set of guidelines/instructions for contributions. Optional: Establish a discussion forum for more general communication with and between users. - -Expectations of responsiveness: - -1. Issues are contributions - and should be met by a thankful attitude. When receiving an item on your issue tracker, the first thing to do is thank the contributor, even if it cannot be addressed right away. -2. If an issue cannot be addressed right away, explain when you plan to address the issue. -3. Do not close issues without responding. If an issue is out of scope for a repository, recommend moving it to a different repository. -4. It is recommended that one or more developers be designated to triage issues. - -## Implementation - -Issue tracker: -Specify the URL for an issue tracker (GitHub is recommended) in the ontology configuration file (YAML) that is used to display ontology details on the OBO Foundry web site. Specification of the tracker is done using the following text (customized for your ontology) within its [metadata file](https://github.com/OBOFoundry/OBOFoundry.github.io/tree/master/ontology): - -`tracker: ` - -Guideline for contributions (recommended): -Create a file called 'CONTRIBUTING.md' ([example](https://github.com/mapping-commons/sssom/blob/master/CONTRIBUTING.md)) in an easy-to-find main folder for the appropriate ontology (for example, in the root directory of the ontology GitHub repository, where one would expect to find LICENSE or README files). Learn more about contribution guidelines [here](http://mozillascience.github.io/working-open-workshop/contributing/)). - -Discussion forum (optional): -Establish a discussion forum (For example, Google groups mailing list, Slack, Twitter). Each of these is specified in the configuration file as given below: - -`mailing_list: ` - -`twitter: ` - -`slack: ` - -## Examples - -Issue tracker: https://github.com/monarch-initiative/mondo/issues - -Mailing list: mondo-users@googlegroups.com - -Twitter: diseaseontology - -Slack: https://geneontologyworkspace.slack.com - -## Counter-Examples - -Specifying a private issue tracker. -Waiting until an issue is resolved before responding, if such resolution comes well after submission of a ticket. - -## Criteria for Review - -There is a functioning public issue tracker for ontology requests specified on the OBO Foundry web site. - -[This check is automatically validated.](checks/fp_020) - -## Feedback and Discussion - -To suggest revisions or begin a discussion pertaining to this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Editorial+WG,principles&title=Principle+%2320+%22Responsiveness%22+%3CENTER+ISSUE+TITLE%3E). - -To suggest revisions or begin a discussion pertaining to the automated validation of this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Technical+WG,automated+validation+of+principles&title=Principle+%2320+%22Responsiveness%22+-+automated+validation+%3CENTER+ISSUE+TITLE%3E). From 56401df12b80c0a7d5603fa486a45cc30c7fb0f2 Mon Sep 17 00:00:00 2001 From: caufieldjh Date: Tue, 11 Feb 2025 15:59:35 -0500 Subject: [PATCH 2/4] Remove targets related to principles --- Makefile | 39 ++++++++++++++------------------------- 1 file changed, 14 insertions(+), 25 deletions(-) diff --git a/Makefile b/Makefile index 1acb07f..7aefabd 100644 --- a/Makefile +++ b/Makefile @@ -33,9 +33,6 @@ RUN = poetry run # All KG .md files KGS := $(wildcard resource/*.md) -# All principles .md files -PRINCIPLES := $(wildcard principles/*.md) - # Path to the source KG-Registry schema SOURCE_SCHEMA = src/kg_registry/kg_registry_schema/schema/kg_registry_schema.yaml @@ -72,31 +69,26 @@ reports: reports/robot: mkdir -p $@ -reports/principles: - mkdir -p $@ +# reports/principles: +# mkdir -p $@ ### Build Configuration Files -# Create the site-wide config file by combining all metadata on resources + principles +# Create the site-wide config file by combining all metadata on resources # and combining with site-wide metadata. # # Note that anything in _config.yml is accessible to any liquid template via the # `sites` object - think of it like the global database # # (this is somewhat hacky, but concatenating these yamls is safe) -_config.yml: _config_header.yml registry/kgs.yml principles/all.yml +_config.yml: _config_header.yml registry/kgs.yml cat $^ > $@.tmp && mv $@.tmp $@ # Sort resources based on the validation (metadata-grid) registry/kgs.yml: reports/metadata-grid.csv ./util/sort-resources.py tmp/unsorted-resources.yml $< $@ && rm -rf tmp -# Extract the metadata from each principle in the principles/ directory, and concatenate -# into a single yaml file in that directory -principles/all.yml: $(PRINCIPLES) - ./util/extract-metadata.py concat-principles -o $@.tmp $^ && mv $@.tmp $@ - # Use a generic yaml->json conversion, but adding a @content registry/kgs.jsonld: registry/kgs.yml ./util/yaml2json.py $< > $@.tmp && mv $@.tmp $@ @@ -191,18 +183,18 @@ build/robot-foreign.jar: | build # Generate the initial dashboard results file # ALWAYS make sure nothing is running on port 25333 # Then boot Py4J gateway to ROBOT on that port -reports/dashboard.csv: registry/kgs.yml | \ -reports/robot reports/principles build/resource build/robot.jar build/robot-foreign.jar - make reboot - ./util/principles/dashboard.py $< $@ --big false +# reports/dashboard.csv: registry/kgs.yml | \ +# reports/robot reports/principles build/resource build/robot.jar build/robot-foreign.jar +# make reboot +# ./util/principles/dashboard.py $< $@ --big false -reports/big-dashboard.csv: reports/dashboard.csv - make reboot - ./util/principles/dashboard.py registry/kgs.yml $@ --big true +# reports/big-dashboard.csv: reports/dashboard.csv +# make reboot +# ./util/principles/dashboard.py registry/kgs.yml $@ --big true -# Combine the dashboard files -reports/dashboard-full.csv: reports/dashboard.csv reports/big-dashboard.csv registry/kgs.yml - ./util/principles/sort_tables.py $^ $@ +# # Combine the dashboard files +# reports/dashboard-full.csv: reports/dashboard.csv reports/big-dashboard.csv registry/kgs.yml +# ./util/principles/sort_tables.py $^ $@ # Generate the HTML grid output for dashboard reports/dashboard.html: reports/dashboard-full.csv @@ -215,7 +207,6 @@ build/dashboard: reports/dashboard.html mkdir -p $@/reports cp $< $@ cp -r reports/robot $@/reports - cp -r reports/principles $@/reports cp -r assets/svg $@/assets rm -rf build/dashboard.zip zip -r $@.zip $@ @@ -226,10 +217,8 @@ build/dashboard: reports/dashboard.html clean-dashboard: build/dashboard rm -rf build/resource rm -rf reports/robot - rm -rf reports/principles rm -rf build/dashboard - # Note this should *not* be run as part of general travis jobs, it is expensive # and may be prone to false positives as it is inherently network-based valid-purl-report.txt: registry/kgs.yml From f069bfd2a82f653b312b4c1f1c5abab7caef913a Mon Sep 17 00:00:00 2001 From: caufieldjh Date: Tue, 11 Feb 2025 15:59:55 -0500 Subject: [PATCH 3/4] Update config file --- _config.yml | 49 ------------------------------------------------- 1 file changed, 49 deletions(-) diff --git a/_config.yml b/_config.yml index 44cc6c3..8bc45cd 100644 --- a/_config.yml +++ b/_config.yml @@ -1241,52 +1241,3 @@ resources: url: https://w3id.org/biopragmatics/resources/uniprot/uniprot.sssom repository: https://github.com/biopragmatics/obo-db-ingest url: https://biopragmatics.github.io/obo-db-ingest/ -principles: -- id: fp-000-summary - layout: principle - title: Overview -- id: fp-001-open - layout: principle - title: Open (principle 1) -- id: fp-002-format - layout: principle - title: Common Format (principle 2) -- id: fp-003-uris - layout: principle - title: URI/Identifier Space (principle 3) -- id: fp-004-versioning - layout: principle - title: Versioning (principle 4) -- id: fp-005-delineated-content - layout: principle - title: Scope (principle 5) -- id: fp-006-textual-definitions - layout: principle - title: Textual Definitions (principle 6) -- id: fp-007-relations - layout: principle - title: Relations (principle 7) -- id: fp-008-documented - layout: principle - title: Documentation (principle 8) -- id: fp-009-users - layout: principle - title: Documented Plurality of Users (principle 9) -- id: fp-010-collaboration - layout: principle - title: Commitment To Collaboration (principle 10) -- id: fp-011-locus-of-authority - layout: principle - title: Locus of Authority (principle 11) -- id: fp-012-naming-conventions - layout: principle - title: Naming Conventions (principle 12) -- id: fp-013-notification - layout: principle - title: Notification of Changes (principle 13) -- id: fp-016-maintenance - layout: principle - title: Maintenance (principle 16) -- id: fp-020-responsiveness - layout: principle - title: Responsiveness (principle 20) From c5f6fddb885125fc76e34563faf25ab898528ad1 Mon Sep 17 00:00:00 2001 From: caufieldjh Date: Tue, 11 Feb 2025 16:02:15 -0500 Subject: [PATCH 4/4] Minor update to entry to trigger new build --- resource/biolink.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/resource/biolink.md b/resource/biolink.md index 61b209d..095bcec 100644 --- a/resource/biolink.md +++ b/resource/biolink.md @@ -24,4 +24,4 @@ license: url: https://creativecommons.org/publicdomain/zero/1.0/ --- -Entity and association taxonomy and datamodel for life-sciences data +Entity and association taxonomy and datamodel for life-sciences data.