docs: add docs section on SPARQL result conversion

Author: lu-pl

docs/rdflib_integration.md

@@ -1,7 +1,81 @@
 # RDFLib Integration
 
 ## SPARQL Result Conversion
-[todo]
+
+As mentioned in the [README](../README.md), `SPARQLWrapper` query methods feature a `convert: bool` flag  for conversion of SPARQL responses to Python result representations.
+
+E.g. if the `convert` parameter is set to `True`, `SPARQLWrapper.query` returns
+
+- a `list` of Python dictionaries with dict-values cast to RDFLib objects for `SELECT` queries
+- a Python `bool` for `ASK` queries
+- an `rdflib.Graph` instance for `CONSTRUCT` and `DESCRIBE` queries.
+
+Not that currently only JSON is supported as a response format for `convert=True` on `SELECT` and `ASK` query results.
+
+
+### JSON Response Conversion of SELECT Query Results
+
+While for graph result conversion (`CONSTRUCT` and `DESCRIBE` queries), the requested `response_format` is simply passed to `rdflib.Graph.parse` along with the response content,
+the `SELECT` query converter logic in `sparqlx` processes response JSON adhering to the [SPARQL 1.2 Query Results JSON Format](https://www.w3.org/TR/sparql12-results-json/) and generates a Python mapping with RDFLib-casted JSON result values;
+i.e. the conversion of `SELECT` query results returns a `list` of mappings with values of type `sparqlx.types.SPARQLResultBindingValue` (a union type `rdflib.URIRef | rdflib.BNode | sparqlx.types.LiteralToPython`).
+
+
+An important divergence from the SPARQL 1.2 Query Results JSON Format lies in how `sparqlx` handles `UNDEF` SPARQL bindings in `SELECT` result conversions.
+While `UNDEF` SPARQL bindings are actually *dropped entirely* for the respective result row in the standard Query Results JSON, `sparqlx` inspects the projection and guarantees stable result shapes by assigning `None` for `UNDEF` bindings.
+
+Consider the following `VALUES` example:
+
+```sparql
+select ?x
+where {
+  values ?x {1 undef}
+}
+```
+
+The raw JSON response for this query will be:
+
+```json
+{
+  "head": {
+	"vars": [
+	  "x"
+	]
+  },
+  "results": {
+	"bindings": [
+	  {
+		"x": {
+		  "datatype": "http://www.w3.org/2001/XMLSchema#integer",
+		  "type": "literal",
+		  "value": "1"
+		}
+	  },
+	  {}
+	]
+  }
+}
+```
+
+Note that the second binding map is empty.
+
+
+The same query with `SPARQLWrapper.query` and `convert=True` produces the following result of type `sparqlx.types.SPARQLResultBinding`:
+
+```python
+[{'x': 1}, {'x': None}]
+```
+
+This normalization of result shapes according to the query projection is convenient for SPARQL result processing e.g. with Pydantic models or the like.
+
+
+The explication of SPARQL `UNDEF` as `None`-bindings in `sparqlx` has subtle consequences that one should be aware of though.
+
+| Query                  | `convert=False`                                                                  | `convert=True`        | Comment                                                                 |
+|------------------------|----------------------------------------------------------------------------------|-----------------------|-------------------------------------------------------------------------|
+| `select ?dne where {}` | `{'head': {'vars': ['dne']}, 'results': {'bindings': [{}]}}`                     | `[{ 'dne': None }]`   | `?dne` is in the projection and therefore present in the converted result. |
+| `select * where {}`    | `{'head': {'vars': []}, 'results': {'bindings': [{}]}}`                          | `[{}]`                | No variables in the projection, so no bindings appear in the con*
+
+
 
 ## `rdflib.Graph` Targets