SHACL documentation

This documentation generation utility prints an application profile specified in SHACL. It supports a subset of SHACL constraints. The generated documentation describes all the properties allowed on each class/shape of the application profile, and includes a diagram, namespace table, introduction, and some metadata at the top of the document. Detailed documentation is available below.

Good examples of how the generated documentation looks like are the European Parliament application profiles or the RDA-FR profile.

  Shapes

Remove Select file Change
You can select multiple files. Supported extensions : .rdf, .ttl, .n3, .trig. Other extensions will be treated as RDF/XML
To have your Shapes in the catalog, add it to the catalog Github repository.
URL of an RDF file. Same extensions as file upload are supported.
Supported syntaxes : Turtle, RDF/XML, JSON-LD, TriG, TriX, N-Quads. We recommend Turtle.

  Options

Enter a 2-letters language code. Labels and notes will be read in this language.
The logo must be accessible at a URL. SVG is not supported if printed in PDF.
Check if you want the UML diagram to be included in the generated documentation. Not all structure of Shapes file can produce a nice UML diagram.

Documentation

Note : the diagram generation is documented in a separate page.

Sample file

To test, and to better understand how the documentation generation works you can download this turtle example of an application profile specified in SHACL , or the corresponding Excel file This Excel file can be converted in SHACL using the SKOS Play xls2rdf conversion tool. All the details about the conversion rules are documented in the converter page. This documentation focuses on which SHACL constraints are used to produce the documentation.

owl:Ontology header

The documentation generation reads the following properties on a owl:Ontology entity in the SHACL file.

Property Type Required Description
dcterms:title if present, or rdfs:label xsd:string Yes Generates the title of the document
dcterms:abstract (+ rdfs:comment) xsd:string No Generates an Abstract section in the documentation, if present. If dcterms:abstract values is null, use rdfs:comment. Content is interpreted as Markdown.
dcterms:description xsd:string No Generates a Description section in the generated documentation, if present. Content is interpreted as Markdown.
adms:versionNodes xsd:string No Generates a Release notes section at the end of the documentation, if present. Content is interpreted as Markdown.
dcat:distribution
(+ dcterms:format + dcat:downloadURL)
IRI or blank node No Generates download links for the various distributions of the application profiles. Each dcat:distribution must point to a resource (IRI or blank node) that have both a dcterms:format indicating the format of the file and a dcat:downloadURL giving the download URL. Supported values for dcterms:format are:
  • https://www.iana.org/assignments/media-types/text/turtle for Turtle distribution
  • https://www.iana.org/assignments/media-types/application/rdf+xml for RDF/XML distribution
  • https://www.iana.org/assignments/media-types/application/n-triples for NTriple distribution
  • https://www.iana.org/assignments/media-types/application/ld+json for JSON-LD distribution
This can be repeated to point to multiple distributions.
foaf:depiction IRI No If present, refer to the URL of a diagram giving a depiction of the application profile, that will be included in the "Diagrams" section of the generated documentation. This can be repeated to include more than one diagram. See the diagram generation documentation for more information.

The following properties are also read on the owl:Ontology to populate the metadata header at the top of the document.

Property Type Required Description
dcterms:modified xsd:dateTime No Shown in the header of the generated documentation
dcterms:created xsd:dateTime No Shown in the header of the generated documentation
dcterms:creator (+ rdfs:label) IRI or Literal No Shown in the header of the generated documentation. If the value is an IRI, and if it has an rdfs:label, use this as the label of the link; otherwise the URI will be shown.
dcterms:dateCopyrighted xsd:dateTime No Shown in the header of the generated documentation
dcterms:issued xsd:dateTime No Shown in the header of the generated documentation
dcterms:license (+ rdfs:label) IRI or Literal No Shown in the header of the generated documentation. If the value is an IRI, and if it has an rdfs:label, use this as the label of the link; otherwise the URI will be shown.
dcterms:publisher (+ rdfs:label) IRI or Literal No Shown in the header of the generated documentation. If the value is an IRI, and if it has an rdfs:label, use this as the label of the link; otherwise the URI will be shown.
dcterms:rightsHolder (+ rdfs:label) IRI or Literal No Shown in the header of the generated documentation. If the value is an IRI, and if it has an rdfs:label, use this as the label of the link; otherwise the URI will be shown.
owl:versionInfo xsd:string No Shown in the header of the generated documentation
doap:repository IRI No Shown in the header of the generated documentation

Example


This is an example of metadata on the owl:Ontology:




This generates the following output:


Prefixes table

The prefixes of the SHACL file are inserted in a ""Namespaces section at the top of the documentation. For example the following prefixes:



Will generate the corresponding output table:

Documentation of Node Shapes

The following properties are read on each sh:NodeShape to populate the header of each section of the generated documentation.

Property Type Required Description
rdfs:label (or skos:prefLabel or rdfs:label on class) xsd:string Yes Label of the NodeShape used as the title of the section in the documentation. If not provided, and if sh:targetClass points to a URI, then a skos:prefLabel or rdfs:label are searched on the target class.
rdf:type rdfs:Class sh:IRI No If the NodeShape is also an instance of rdfs:Class, then its URI will be displayed under the section title.
rdfs:comment (or skos:definition or rdfs:comment on class) xsd:string No Small descriptive paragraph under the section title. If not provided, and if sh:targetClass points to a URI, then a skos:definition or rdfs:comment are searched on the target class.
sh:targetClass sh:IRI No The class to which the NodeShape applies.
sh:target/sh:select sh:Literal No If the target of the Shape is provided as a SPARQL query, it will be included in the section header.
sh:closed xsd:boolean No Indicates if the shape is closed.
sh:pattern xsd:string No Regex specifying the URI pattern that the targets of the NodeShape must conform to.
skos:example IRI or xsd:string No Example of an IRI for a target of this NodeShape. Can be given as an IRI reference or a string.
sh:order xsd:integer No Sections of the generated documentation are sorted according to sh:order on sh:NodeShape, or by label if not present.

This is how it can typically look like in SHACL:



This generates the following output:









Documentation of Property Shapes

The following properties are read on each sh:PropertyShape to populate the properties table in the generated documentation.

Property Expected value Required Description
sh:path IRI Yes Property or property path - each property shape generates one line in the table.
sh:name (or skos:prefLabel or rdfs:label) xsd:string No Used to display the name of the property. If not provided, and if sh:path points to a URI, then a skos:prefLabel or rdfs:label are searched on the property URI indicated in the sh:path. This implies the SHACL file also contains the OWL definition. Otherwise, the column will be empty.
sh:description (or skos:definition or rdfs:comment) xsd:string No Populates the Description column of the table. If not provided, and if sh:path points to a URI, then a skos:definition or rdfs:comment is searched on the property URI indicated in the sh:path. This implies the SHACL file also contains the OWL definition. Otherwise the column will be empty.
sh:minCount / sh:maxCount xsd:integer No Used to populate the Cardinality column of the table
sh:node IRI of a NodeShape One of sh:node, sh:class, sh:nodeKind, sh:datatype, sh:or, sh:hasValue must be provided Used to populate the Expected value column, see below.
sh:class IRI of a class One of sh:node, sh:class, sh:nodeKind, sh:datatype, sh:or, sh:hasValue must be provided. Used to populate the Expected value column, see below.
sh:nodeKind Value can be either sh:IRI or sh:Literal One of sh:node, sh:class, sh:nodeKind, sh:datatype, sh:or, sh:hasValue must be provided. Used to populate the Expected value column, see below.
sh:datatype IRI of a datatype One of sh:node, sh:class, sh:nodeKind, sh:datatype, sh:or, sh:hasValue must be provided. Used to populate the Expected value column, see below.
sh:hasValue RDF List of values One of sh:node, sh:class, sh:nodeKind, sh:datatype, sh:or, sh:hasValue must be provided. Used to populate the Expected value column, see below.
sh:or RDF List of blank nodes with a sh:node One of sh:node, sh:class, sh:nodeKind, sh:datatype, sh:or, sh:hasValue must be provided. Used to populate the Expected value column, see below.
sh:in RDF List of values No Used to indicate the possible list of values, as an additionnal information in the Expected value column.
sh:order xsd:integer No Lines of the generated table are sorted according to sh:order.

The Expected value column is generated by looking at the following properties in order of precedence :

  • Use sh:hasValue if present.
  • Otherwise use sh:class
  • Otherwise use sh:node
  • Otherwise use sh:datatype
  • Otherwise use sh:nodeKind
  • Otherwise use sh:or; in this case, get the list items and read sh:node on each of them.
  • Otherwise the column is left empty.

Additionally, if sh:in is present, it is inserted as an additional information in the Expected value column.

This generates the following output: