From baa237351f124fedcebc73b0eeda52384b485e10 Mon Sep 17 00:00:00 2001 From: Carlo van Driesten Date: Fri, 11 Sep 2026 16:34:30 +0200 Subject: [PATCH] docs(owl): document deterministic serialization and --diff-stable Describe in the gen-owl documentation what RDFC-1.0 canonicalization guarantees for standard RDF, why its sequential blank-node numbering can still produce noisy diffs, and that --diff-stable reduces that churn without guaranteeing minimal diffs. Note that the option also exists on gen-rdf, gen-shacl and gen-shex --format rdf, and that graphs that are not standard RDF, such as gen-shacl --include-annotations output with a non-CURIE annotation tag, are serialized by rdflib with a warning, where --diff-stable has no effect. Signed-off-by: jdsika --- docs/generators/owl.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/generators/owl.rst b/docs/generators/owl.rst index 4b6f076fe8..3b0a0aa2c7 100644 --- a/docs/generators/owl.rst +++ b/docs/generators/owl.rst @@ -311,6 +311,28 @@ Other examples translation of Biolink schema to OWL +Deterministic output +^^^^^^^^^^^^^^^^^^^^ + +``gen-owl`` canonicalizes the graph with `RDFC-1.0 `_ +before serializing it. For standard RDF, repeated runs over the same schema +therefore produce byte-identical Turtle, and checked-in artifacts do not change +between runs. + +RDFC-1.0 numbers blank nodes in canonical order (``_:c14n0``, ``_:c14n1``, ...), +so adding a statement can renumber unrelated blank nodes. ``--diff-stable`` +derives labels from blank-node neighbourhoods instead, which reduces this churn +but does not guarantee minimal diffs; see :ref:`rdf-in-version-control`, which +also names the optional dependency it needs. The option is also available on +``gen-rdf``, ``gen-shacl`` and ``gen-shex --format rdf``. + +Graphs that are not standard RDF, with a relative IRI or a literal as a +predicate, cannot be canonicalized under RDFC-1.0; ``gen-shacl +--include-annotations`` writes such a predicate for an annotation whose tag is +not a CURIE. They are serialized by rdflib instead, with an +``RDFCanonicalizationWarning``, and ``--diff-stable`` has no effect on them. + + Docs ----