• XQRS
  • Docs
  • Controlling Output Serialization

Controlling Output Serialization

Controlling how different types of content is formatted and encoded

You can control the way in which XQRS serializes and encodes the content produced from a function, to do this you use the annotations found in the output namespace.

declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization";

1. Serializing XML, XHTML or HTML

There are many options and ways that you can serialize an document, please check the XQuery Serialization Support and Reference Table for detailed information. Consider the following example

declare
  %rest:path("/get/{$uri}")
  %output:method("xml")
  %output:encoding("iso-8859-1")
  %output:indent("yes")
  %output:media-type("application/special+xml")
function get($uri as xs:string) {
  fn:doc($uri)
};

2. Serializing RDF

By default when a function produces a sequence of sem:triple items, XQRS will serialize them in Turtle format. You can change the serialization format by setting the %output:method to one of the following values: n3, nquad, ntriple, rdfjson, rdfxml, trig, triplexml or turtle.

Consider the following example

(:
  Service /convert-rdf converts any serialization format of RDF
  into any other serialization format of RDF, purely via
  Content-Negotiation alone i.e. Accept, Content-Type headers
:)

declare namespace rest = "http://exquery.org/ns/restxq";
declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization";

declare
  %rest:path("/convert-rdf") %output:method("n3") %rest:POST("{$data}")
  %rest:produces("text/n3")
function convert-to-n3($data as sem:triple*) { $data };

declare
  %rest:path("/convert-rdf") %output:method("nquad") %rest:POST("{$data}")
  %rest:produces("application/n-quads") 
function convert-to-nquad($data as sem:triple*) { $data };

declare
  %rest:path("/convert-rdf") %output:method("ntriple") %rest:POST("{$data}")
  %rest:produces("application/n-triples")
function convert-to-ntriple($data as sem:triple*) { $data };

declare
  %rest:path("/convert-rdf") %output:method("rdfjson") %rest:POST("{$data}")
  %rest:produces("application/rdf+json")
function convert-to-rdfjson($data as sem:triple*) { $data };

declare
  %rest:path("/convert-rdf") %output:method("rdfxml") %rest:POST("{$data}")
  %rest:produces("application/rdf+xml")
function convert-to-rdfxml($data as sem:triple*) { $data };

declare
  %rest:path("/convert-rdf") %output:method("trig") %rest:POST("{$data}")
  %rest:produces("application/trig")
function convert-to-trig($data as sem:triple*) { $data };

declare
  %rest:path("/convert-rdf") %output:method("triplexml") %rest:POST("{$data}")
  %rest:produces("application/vnd.marklogic.triples+xml")
function convert-to-triplexml($data as sem:triple*) { $data };

declare
  %rest:path("/convert-rdf") %output:method("turtle") %rest:POST("{$data}")
  %rest:produces("text/turtle")
function convert-to-turtle($data as sem:triple*) { $data };

3. Serializing SPARQL Results

You can serialize SPARQL results to either XML, JSON or CSV formats by setting the %output:method to sparql-results-xml, sparql-results-json or sparql-results-csv respectively. Consider the following example

(:
  The /sparql service runs a SPARQL Query and returns the SPARQL results
  in either XML, JSON or CSV format based on Content Negotiation
:)

declare namespace rest = "http://exquery.org/ns/restxq";
declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization";

declare %rest:path("/sparql")
        %output:method("sparql-results-xml")
        %rest:produces("application/sparql-results+xml", "*/xml")
        %rest:POST("{$query}")
function sparql-xml-results($query as xs:string) {
  sem:sparql($query)
};

declare %rest:path("/sparql")
        %output:method("sparql-results-xml")
        %rest:produces("application/sparql-results+json", "application/json")
        %rest:POST("{$query}")
function sparql-json-results($query as xs:string) {
  sem:sparql($query)
};

declare %rest:path("/sparql")
        %output:method("sparql-results-csv")
        %rest:produces("text/csv")
        %rest:POST("{$query}")
function sparql-csv-results($query as xs:string) {
  sem:sparql($query)
};

4. Serializing JSON

You can serialize to JSON by setting the %output:method to json

declare
  %rest:path("/my-json")
  %output:method("json")
  %rest:query-param-1("v1", "{$v1}")
  %rest:query-param-2("v2", "{$v2}")
function my-json($v1 as xs:string, $v2 as xs:string) {
  object-node {
    "a": $v1,
    "b": $v2
  }
};

5. XQuery Serialization Support and Reference Table

Annotation Valid values Description
method xml, html, xhtml, text, json

n3, nquad, ntriple, rdfjson, rdfxml, trig, triplexml, turtle

sparql-results-xml,
sparql-results-json,
sparql-results-csv		 Set the primary serialization method
encoding Specifies the encoding to use when serializing the response
output-encoding Specifies the encoding to use when serializing the response
item-separator A string to separate a sequence of result items with. The default is a line feed character
media-type Set the Content-Type header of the HTTP Response with a mime type, e.g. text/plain, application/xml, etc
byte-order-mark yes, no Should a byte order mark be emitted
output-sgml-character-entities normal, none, math, pub Specifies if character entities should be output upon serialization.
cdata-section-elements A list of space-separated QNames to output as CDATA sections.
use-character-maps xdmp:sgml-entities-normal, xdmp:sgml-entities-math, xdmp:sgml-entities-pub Use Character Maps, separate different values with spaces
indent yes, no Should content be pretty-printed (indented)
indent-untyped yes, no Should content be pretty-printed (indented)
indent-tabs yes, no Should tab characters be used instead of 8 space blocks when indenting
include-content-type yes, no Include the content-type declaration when serializing the node
escape-uri-attributes yes, no Escape URI Attributes
doctype-public A public identifier, which is the public identifier to use on the emitted DOCTYPE
doctype-system A system identifier, which is the system identifier to use on the emitted DOCTYPE
omit-xml-declaration yes, no Omit the XML Declaration
standalone yes, no Is the document standalone
normalization-form NFC, NFD, NFKD Set the Unicode Normalization Form
default-attributes yes, no Should attributes implicitly by defaults in a Schema be used in serialization

Docs

TOP