.Dd March 6, 2021
.Dt SERDI 1
.Os Serd 0.30.11
.Sh NAME
.Nm serdi
.Nd read and write RDF syntax
.Sh SYNOPSIS
.Nm serdi
.Op Fl CSabefhlmqtvx
.Op Fl I Ar base
.Op Fl V Ar checks
.Op Fl c Ar prefix
.Op Fl g Ar pattern
.Op Fl i Ar syntax
.Op Fl k Ar bytes
.Op Fl o Ar syntax
.Op Fl p Ar prefix
.Op Fl r Ar root
.Op Fl s Ar string
.Op Fl w Ar filename
.Ar input ...
.Sh DESCRIPTION
.Nm
is a fast command-line utility for streaming and processing RDF data.
It reads an RDF document and writes the data again,
possibly transformed and/or in a different syntax.
By default,
the input syntax is guessed from the file extension,
and output is written in NTriples or NQuads.
.Pp
.Nm
can be used to check for syntax errors,
convert from one syntax to another,
pretty-print documents,
or transform URIs and blank node IDs.
.Pp
The options are as follows:
.Pp
.Bl -tag -compact -width 3n
.It Fl I Ar base
Input base URI.
Relative URI references in the input will be resolved against this.
When the input is a file,
the URI of the file is automatically used as the base URI.
This option can be used to override that,
or to provide a base URI for input from stdin or a string.
.Pp
.It Fl C
Convert literals to canonical form.
Literals with supported XSD datatypes will be parsed and rewritten canonically.
All numeric datatypes are supported, as well as
.Vt boolean ,
.Vt duration ,
.Vt datetime ,
.Vt time ,
.Vt hexBinary ,
and
.Vt base64Binary .
.Pp
.It Fl S
Stream model quickly without inlining.
This only has an effect when a model is used, and disables searching and statement reordering for pretty printing.
Statements will be written in simple sorted order, which is faster, but may result in less readable output in Turtle or TriG.
.Pp
.It Fl V Ar checks
Validate data with the given
.Ar checks ,
which is a regular expression that matches a set of check names to enable,
or the special value
.Dq all
which enables all checks.
See
.Sx VALIDATION
below for a detailed list of all checks.
Validation requires a model, so this option implicitly enables
.Fl m .
.Pp
.It Fl X Ar checks
Exclude
.Ar checks
from the set of checks enabled by a previous
.Fl V
option.
This is typically after
.Fl V Ar all
to suppress a few specific checks.
.Pp
.It Fl a
Write ASCII output.
If this is enabled, all non-ASCII characters will be escaped, even if the output syntax allows them to be written in UTF-8.
.Pp
.It Fl b
Bulk output writing.
If this is enabled, output will be written a page at a time, rather than a byte at a time.
.Pp
.It Fl c Ar prefix
Chop
.Ar prefix
from matching blank node IDs.
This is the inverse of
.Fl p .
.Pp
.It Fl e
Eat input one character at a time, rather than a page at a time which is the default.
This is useful when reading from a pipe since output will be generated immediately as input arrives, rather than waiting until an entire page of input has arrived.
With this option serdi uses one page less memory, but will likely be significantly slower.
.Pp
.It Fl f
Fast and loose mode.
This disables shortening URIs into prefixed names or relative URI references.
If the model is enabled, then this writes the model quickly in sorted order.
Note that doing so with TriG or Turtle may make the output ugly,
since blank nodes will not be inlined.
.Pp
.It Fl g Ar pattern
Filter statements that match
.Ar pattern
(like grep).
.Ar pattern
should be a single statement written in NTriples or NQuads.
.Pp
.It Fl h
Print the command line options.
.Pp
.It Fl i Ar syntax
Read input as
.Ar syntax .
Case is ignored, valid values are:
.Dq NQuads ,
.Dq NTriples ,
.Dq TriG ,
and
.Dq Turtle .
.Pp
.It Fl k Ar bytes
Parser stack size.
For performance reasons, parsing is performed with a fixed-size stack.
By default, the stack is one page (4096 bytes), which should be sufficient for parsing most documents.
This option can be used to increase or decrease the amount of memory available for parsing.
It must be large enough to fit one statement, with some extra space for internal records.
Something around twice the length of the longest statement in text (as if it were written in NTriples or NQuads) is a reasonable value.
.Pp
.It Fl l
Lax (non-strict) parsing.
If this is enabled, recoverable syntax errors will print a warning, but parsing will proceed starting at the next statement if possible.
Note that data may be lost when using this option.
.Pp
.It Fl m
Build a model in memory.
This loads all of the input into memory before writing the output.
This will reorder statements and eliminate duplicates, at the cost of performance and memory consumption.
When writing TriG or Turtle, this may enable better pretty-printing with more inline descriptions.
.Pp
.It Fl o Ar syntax
Write output as
.Ar syntax .
Case is ignored, valid values are:
.Dq empty ,
.Dq NQuads ,
.Dq NTriples ,
.Dq TriG ,
and
.Dq Turtle .
When
.Dq empty
is given, output is suppressed, so only errors will be printed.
.Pp
.It Fl p Ar prefix
Add
.Ar prefix
to blank node IDs.
This can be used to avoid clashes between blank node IDs in input documents.
.Pp
.It Fl q
Suppress all output except data.
.Pp
.It Fl r Ar root
Keep relative URIs within a
.Ar root
URI.
This will avoid creating any relative URI references with leading path segments like
.Dq ../
that enter a parent of
.Ar root .
.Pp
.It Fl s Ar string
Parse
.Ar string
input instead of a file.
.Pp
.It Fl t
Write terser output without newlines.
.Pp
.It Fl v
Display version information and exit.
.Pp
.It Fl w Ar filename
Write output to the given
.Ar filename
instead of stdout.
.Pp
.It Fl x
Support parsing variable nodes.
Variables can be written in SPARQL style, for example
.Dq ?var
or
.Dq $var .
.El
.Sh VALIDATION
.Bl -tag -compact -width 3n
.It Va allValuesFrom
Checks that all properties with owl:allValuesFrom restrictions have valid value types.
.It Va cardinalityEqual
Checks that any instance of a class with a owl:cardinality property restriction has exactly that many values of that property.
.It Va cardinalityMax
Checks that any instance of a class with a owl:maxCardinality property restriction has no more than that many values of that property.
.It Va cardinalityMin
Checks that any instance of a class with a owl:minCardinality property restriction has at least that many values of that property.
.It Va classLabel
Checks that every rdfs:Class has an rdfs:label.
.It Va classType
Checks that the value of every rdf:type property is defined as an rdfs:Class.
.It Va datatypeProperty
Checks that datatype properties have literal (not instance) values.
.It Va datatypeType
Checks that every datatype is defined as a rdfs:Datatype.
.It Va deprecatedClass
Checks that there are no instances of deprecated classes.
.It Va deprecatedProperty
Checks that there are no uses of deprecated properties.
.It Va functionalProperty
Checks that no instance has several values of a functional property.
.It Va instanceLiteral
Checks that there are no instances where a literal is expected.
.It Va instanceType
Checks that every instance with an explicit type matches that type.
This is a broad check that triggers other type-related checks, but mainly it will check that every instance of a class conforms to any restrictions on that class.
.It Va inverseFunctionalProperty
Checks that at most one instance has a given value of an inverse functional property.
.It Va literalInstance
Checks that there are no literals where an instance is expected.
.It Va literalMaxExclusive
Checks that literal values are not greater than or equal to any applicable xsd:maxExclusive datatype restrictions.
.It Va literalMaxInclusive
Checks that literal values are not greater than any applicable xsd:maxInclusive datatype restrictions.
.It Va literalMinExclusive
Checks that literal values are not less than or equal to any applicable xsd:minExclusive datatype restrictions.
.It Va literalMinInclusive
Checks that literal values are not less than any applicable xsd:minInclusive datatype restrictions.
.It Va literalPattern
Checks that literals with xsd:pattern restrictions match the regular expression pattern for their datatype.
.It Va literalRestriction
Checks that literals with supported restrictions conform to those restrictions.
This is a high-level check that triggers the more specific individual literal restriction checks.
.It Va literalValue
Checks that literals with supported XSD datatypes are valid.
The set of supported types is the same as when writing canonical forms.
.It Va objectProperty
Checks that object properties have instance (not literal) values.
.It Va plainLiteralDatatype
Checks that there are no typed literals where a plain literal is expected.
A plain literal may have an optional language tag, but not a datatype.
.It Va predicateType
Checks that every predicate is defined as an rdf:Property.
.It Va propertyDomain
Checks that any instance with a property with an rdfs:domain is in that domain.
.It Va propertyLabel
Checks that every rdf:Property has an rdfs:label.
.It Va propertyRange
Checks that the value for any property with an rdfs:range is in that range.
.It Va someValuesFrom
Checks that instances of classes with owl:someValuesFrom property restrictions have at least one matching property value.
.It Va subclassCycle
Checks that no class is a sub-class of itself, recursively.
This ensures that the graph is acyclic with respect to rdfs:subClassOf.
.It Va subpropertyCycle
Checks that no property is a sub-property of itself, recursively.
This ensures that the graph is acyclic with respect to rdfs:subPropertyOf.
.El
.Sh EXIT STATUS
.Nm
exits with a status of 0, or non-zero if an error occured.
.Sh SEE ALSO
.Bl -item -compact
.It
.Lk http://drobilla.net/software/serd/
.It
.Lk http://gitlab.com/drobilla/serd/
.El
.Sh STANDARDS
.Bl -item
.It
.Rs
.%A W3C
.%T RDF 1.1 NQuads
.%D February 2014
.Re
.Lk https://www.w3.org/TR/n-quads/
.It
.Rs
.%A W3C
.%D February 2014
.%T RDF 1.1 NTriples
.Re
.Lk https://www.w3.org/TR/n-triples/
.It
.Rs
.%A W3C
.%T RDF 1.1 TriG
.%D February 2014
.Re
.Lk https://www.w3.org/TR/trig/
.It
.Rs
.%A W3C
.%D February 2014
.%T RDF 1.1 Turtle
.Re
.Lk https://www.w3.org/TR/turtle/
.El
.Sh AUTHORS
.Nm
is a part of serd, by
.An David Robillard
.Mt d@drobilla.net .