Merge pull request #33 from casework/document_sparql_prefix_order_behavior

Document prefix inheritance

Author: kchason

README.md

@@ -69,6 +69,8 @@ Two commands are provided to generate output from a SPARQL query and one or more
 
 These commands can be used with any RDF files to run arbitrary SPARQL queries.  They have one additional behavior tailored to CASE: If a path query is used for subclasses, the CASE subclass hierarchy will be loaded to supplement the input graph.  An expected use case of this feature is subclasses of `ObservableObject`.  For instance, if a data graph included an object with only the class `uco-observable:File` specified, the query `?x a/rdfs:subClassOf* uco-observable:ObservableObject` would match `?x` against that object.
 
+Note that prefixes used in the SPARQL queries do not need to be defined in the SPARQL query.  Their mapping will be inherited from their first definition in the input graph files.  However, input graphs are not required to agree on prefix mappings, so there is potential for confusion from input argument order mattering if two input graph files disagree on what a prefix maps to.  If there is concern of ambiguity from inputs, a `PREFIX` statement should be included in the query, such as is shown in [this test query](tests/case_utils/case_sparql_select/subclass.sparql).
+
 
 #### `case_sparql_construct`
 

case_utils/case_sparql_construct/__init__.py

@@ -60,7 +60,7 @@ def main() -> None:
       help="Override extension-based format guesser."
     )
     parser.add_argument("out_graph")
-    parser.add_argument("in_sparql")
+    parser.add_argument("in_sparql", help="File containing a SPARQL CONSTRUCT query.  Note that prefixes not mapped with a PREFIX statement will be mapped according to their first occurrence among input graphs.")
     parser.add_argument("in_graph", nargs="+")
     args = parser.parse_args()
 

case_utils/case_sparql_select/__init__.py

@@ -74,7 +74,7 @@ def main() -> None:
       "out_table",
       help="Expected extensions are .html for HTML tables or .md for Markdown tables."
     )
-    parser.add_argument("in_sparql")
+    parser.add_argument("in_sparql", help="File containing a SPARQL SELECT query.  Note that prefixes not mapped with a PREFIX statement will be mapped according to their first occurrence among input graphs.")
     parser.add_argument("in_graph", nargs="+")
     args = parser.parse_args()