Clarify expected attributes rather than returning internal server error(s) in response

[lewismc]

@nicholascar this is some feedback I gathered through the process of deploying pyLODE at cor.esipfed.org/pylode

pyLODE seems too strict as it triggers critical errors (exposed as "internal server errors" via http) if the ontology fails to include some expected attributes. It would be better to give an explanation in the rendering than to fail in such a dramatic way.

@carueda can you please provide an example?

[carueda]

Thanks @lewismc for entering this. I saw this while testing the pyLODE deployment but didn't capture the actual stacktraces. Will try to do that next.

(EDIT: Changed the example to a more relevant for COR, but similar effect.)

Example: http://cor.esipfed.org/ont/~jyu/nug

displayed ok on the COR interface

but not via pyLODE, http://cor.esipfed.org/pylode?url=http://cor.esipfed.org/ont/~jyu/nug

this triggers an "internal server error". Will capture and report the stacktrace for this.

[carueda]

Traceback (most recent call last):
  File "/home/cor-admin1/pyLODE/pylode/cli.py", line 206, in <module>
    main(sys.argv[1:])
  File "/home/cor-admin1/pyLODE/pylode/cli.py", line 200, in main
    print(h.document())
  File "/home/cor-admin1/pyLODE/pylode/makedocco.py", line 181, in document
    return p.generate_document()
  File "/home/cor-admin1/pyLODE/pylode/docprofile_owlp.py", line 1090, in generate_document
    self._extract_metadata()
  File "/home/cor-admin1/pyLODE/pylode/docprofile_owlp.py", line 412, in _extract_metadata
    "Your ontology does not indicate any form of label or title. "
ValueError: Your ontology does not indicate any form of label or title. You must declare one of the following for your ontology: rdfs:label, dct:title, skos:prefLabel
[2020-05-15 17:02:08 +0000] [22793] [ERROR] Error handling request /lode?url=http://cor.esipfed.org/ont/~jyu/nug
Traceback (most recent call last):
  File "/home/cor-admin1/pyLODE/.env/local/lib/python3.6/site-packages/gunicorn/workers/sync.py", line 134, in handle
    self.handle_request(listener, req, client, addr)
  File "/home/cor-admin1/pyLODE/.env/local/lib/python3.6/site-packages/gunicorn/workers/sync.py", line 175, in handle_request
    respiter = self.wsgi(environ, resp.start_response)
  File "falcon/api.py", line 274, in falcon.api.API.__call__
  File "falcon/api.py", line 269, in falcon.api.API.__call__
  File "/home/cor-admin1/pyLODE/pylode/server.py", line 11, in on_get
    resp.body = subprocess.check_output(cmd, shell=True)
  File "/usr/lib64/python3.6/subprocess.py", line 356, in check_output
    **kwargs).stdout
  File "/usr/lib64/python3.6/subprocess.py", line 438, in run
    output=stdout, stderr=stderr)
subprocess.CalledProcessError: Command 'cd ./bin && ./pylode.sh -u http://cor.esipfed.org/ont/~jyu/nug -c true' returned non-zero exit status 1.

[nicholascar]

OK, so the error it generated here was Your ontology does not indicate any form of label or title.. Title's one of the very few one of the very few must have elements! Usually, if something else is missing, it just doesn't create that snipped of documentation.

I'm going to start adding in pre-documentation validation with SHACL files so you can say "document this, only if it validates" and it will spit out standard SHACL errors and warning (that it gets from using pySHACL).

Would this be the kind of output you'd prefer? How else should errors be presented, given that no title is one of very few it can't handle?

[carueda]

Thanks @nicholascar , Yes, I'd say that's preferable in general. In any case, imo the tool should react in a more graceful way. Wdyt @lewismc ?

[lewismc]

+1

[nicholascar]

One thing the tool does now - and this can be changed - is to put a black box in the HTML to indicate that's where someone might put an image. In the case of a missing title, should I put in the text YOUR TITLE HERE to prompt for it or should I just leave it blank? I like the idea of really hassling people into doing the right thing, hence the current Error on no title.

[graybeal]

I like the ideas but would appreciate more subtlety. Keep in mind not every ontology may specify its title or image with the same annotations.

Images are likely to be very uncommon at first, so at most i'd put an empty white box with delicate 10% gray lines for the picture.

For the title, I think it is more useful to explicitly show the lack of a title. Perhaps a 75% gray italicized {No title found} would be more than enough.

[nicholascar]

Keep in mind not every ontology may specify its title or image with the same annotations.

My major use goal for pyLODE is to improve ontology annotations! If someone wants to document an ontology but doesn't include basic annotations.... just no!

I agree we don't necessarily have to completely fail when certain annotations are missing but I think we really should strongly indicate that the annotations should be added. Use to date of pyLODE has seen experienced ontologists (with first names such as Simon & Armin!) improve their annotations after seeing sub-standard rendering.

Images are likely to be very uncommon at first

Yes, I can tone this down, but will it matter? The thing that the black box does is to prompt either for its replacement with an image or just its removal. A grey box would have the same effect.

Perhaps a 75% gray italicized {No title found}

OK, will do that.

[graybeal]

I think you misunderstood my point. I was trying to say that there are many members of the semantic community who have been working over the last 15 years in good faith to produce good ontologies, with good annotations. The standards AND the best practices have changed multiple times over that period. Assuming that the latest specification/recommendation is THE ONLY way to do annotations may leave behind resources that have been developed in good faith, and still have useful content to offer even if they may not be updated any time in the next few years.

So my request is just to be open to those possibilities, and to not make your presentation of the ontology look less attractive in an attempt to make those (mostly historical resources) get better. You are already strongly encouraging everyone who is actively developing ontologies (and COR, and MMI ORR, and other repos like I hope OntoPortal) to do the right thing. That improvement will happen thanks to your work, and I thank you hugely for that!

[nicholascar]

Partly addressed addressed by Commit https://github.com/RDFLib/pyLODE/commit/ff46a7a5b9c0d7480a033a287a7a2f31f4173713

See example of the AGRIF ontology with no image or title: https://raw.githack.com/RDFLib/pyLODE/master/pylode/examples/agrif-notitle.html

The standards AND the best practices have changed multiple times over that period.

I get that. The major fix for this, in terms of what pyLODE can do, is to allow different profiles to be used. So far I've only enabled a so-called OWLP (profile of OWL) and a SKOSP (profile of SKOS) but I'm now working on an Australian Government Ontology Profile which, when complete, will define a few extensions to OWLP and pyLODE will be able to be told to use that particular profile, as per https://github.com/RDFLib/pyLODE/#profiles.

I have thought about the MOD ontology previously (see the very early Issue 6!) and, I suppose any number of other profiles, if other people were willing to contribute them!

I need to:

• improve the documentation about what is required for a pyLODE profile
• provide more pyLODE profile examples (like the Aust Gov one)
• find someone else to implement one to show it can be done
• try and identify ontology documentation styles in use and cater for some

I stepped up to managing the RDFlib Python toolkits actually in order to improve the code on which pyLODE depends...

[nicholascar]

Further addressing part of this Issue by auto-removing Overview image from HTML if served by Falcon since an Overview image can never be auto-generated by pyLODE in https://github.com/RDFLib/pyLODE/commit/24504673ca75a6481b59fee6a74ab49d1a1553ab.

[lewismc]

@nicholascar has any commit resulted from this work yet? If so I can update pyLODE in our ESIP system. Thank you

[nicholascar]

@lewismc yes, there are a series of commits addressing this and making a few other improvements now, such as an addition to your Falcon code to remove the unsightly image blocks when auto-generating documentation. I've gone one better than commits though: there's a new 2.4 release now that you can use (or just master).

[lewismc]

Excellent. We'll upgrade. Thank you 👍