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.
Note : the diagram generation is documented in a separate page.
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.
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:
|
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 |
This is an example of metadata on the owl:Ontology:
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:
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:
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 :
sh:hasValue
if present.sh:class
sh:node
sh:datatype
sh:nodeKind
sh:or
; in this case, get the list items and read sh:node
on each of them.Additionally, if sh:in
is present, it is inserted as an additional information in the Expected value column.
This generates the following output: