INCATools/dead_simple_owl_design_patterns

Simplify generated schema doc

Opened this issue · 2 comments

dosumis commented

The current autogenerated schema doc is overly complicated in the sections that deference definitions.

This would be sufficient:

  • equivalentTo:
    • text (string): A print format string in OWL Manchester syntax. Each entry must correspond to an entry in o the name of a var in the var field of the pattern. Entries in single quotes must correspond to the labels of entries in owl_entity dictionaries (classes, relations, dataProperties).
    • vars (list): An ordered list of variables for substitution into the accompanying print format string. Each entry must correspond to the name of a variable specified in either the 'vars' field or the data_var field of the pattern
    • annotations (list)
      • annotationProperty (string): A string corresponding to the rdfs:label of an owl annotation property. If the annotation property has no label, the shortForm ID should be used. The annotation property must be listed in the annotation property dictionary.'.
      • text (string): A print format string.
      • vars (list): An ordered list of variables for substitution into the accompanying print format string. Each entry must correspond to the name of a variable specified in either the 'vars' field or the data_var field of the pattern. Where an OWL entity is specified, the label for the OWL entity should be used in the substitution. An empty var list can be specified simply by leaving this field out.
      • annotations (list)
        • ...

Note lack of reference names internal to pattern (no printf_owl). This makes sense - a semantically identical pattern could be written with all of the nested structure explicitly repeated under every primary property. I don't see any need for quoting.

I may be wrong, but I also think it is sufficient to just list type (string or list) in brackets, inferring that a list of sets of the keys nested underneath are permitted, rather than including an 'items' keyword.

Deal with recursive structure implicitly by using an ellipsis at the first level of recursion.

dosumis commented

Note - above should be compatible with mkdocs (I think)