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.

This documentation generation utility also supports SHACL-based dataset statistics documentation generation

Shapes

Upload

Remove Select file Change
You can select multiple files. Supported extensions : .rdf, .ttl, .n3, .trig, or .zip. You can also upload Excel files (see SHACL in Excel).

Select from Shapes catalog
To have your Shapes in the catalog, add it to the catalog Github repository.

URL
URL of an RDF file. Same extensions as file upload are supported.

Copy/paste SHACL Rules content
Supported syntaxes : Turtle, RDF/XML, JSON-LD, TriG, TriX, N-Quads. We recommend Turtle.

Options

Language of the generated documentation
Enter a 2-letters language code. Labels and notes will be read in this language.

Insert a logo
The logo must be accessible at a URL. SVG is not supported if printed in PDF.

Include diagram in the generated documentation 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.

Include a diagram in each section Check if you want a small UML diagram to be included in each section of the generated documentation.

Hide Properties Not display properties

Output format

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` (can be repeated)	sh:IRI	No	The class to which the NodeShape applies. This can be repeated multiple times
`sh:targetSubjectsOf` or `sh:targetObjectsOf`	sh:IRI	No	The property for which this shape will target the subjects or the objects.
`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.
`rdfs:subClassOf` or `sh:targetClass/rdfs:subClassOf`	sh:IRI	No	If the NodeShape itself or its target class are subclasses of another class, then this is indicated in the header. Also note that the properties table will be populated with property shapes from the super classes, in different sections "ï¿½ la" schema.org.

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:

Additionally, if skos:example is present, one new example column show in the properties table.

Dataset statistics documentation

Introduction

A variant of this documentation generation utility generates a documentation of a dataset statistics information, based on a certain SHACL profile. This documentation is useful to provide information about the distribution of the data in the dataset. The following displayed are printed:

Total number of triples in the dataset
Number of instances of each shape/class
Number of occurrences of each property shape
Number of distinct values of each property shape
For properties with a small number of values, the number of occurrences of each value, in a pie-chart diagram

These counts are produced by the SHACL generation algorithm, following this structure, which is an extension of the VOID vocabulary.

How to use it

To trigger this feature, you need to upload a file that encodes a SHACL specification, PLUS some statistics information. Precisely it needs to contain :

"node shape partitions" : resources (optionaly of type void:Dataset), with a dcterms:conformsTo predicate pointing a NodeShape, and with a void:entities predicate, holding an integer value, which expresses the number of targets of the node shape.
"property shape partitions" : resources (optional of type void:Dataset), that is itself the object of a void:propertyPartition from a "node shape partition" entity, and that is the subject of :
- a dcterms:conformsTo pointing to a property shape.
- a void:triples predicate holding an integer value, and representing the number of occurrences of the property shape path.
- a void:distinctObjects predicate holding an integer value, and representing the number of distinct values of the property shape path.

Sample file

To test this feature, you can use this provided sample file.

What it does

Documentation header

...

Documentation section

...

Properties table

...