diff --git a/docs/assets/images/img-list-english-colors.png b/docs/assets/images/img-list-english-colors.png new file mode 100644 index 000000000..0c1d49833 Binary files /dev/null and b/docs/assets/images/img-list-english-colors.png differ diff --git a/docs/assets/images/img-list-english-example.png b/docs/assets/images/img-list-english-example.png index a6ad2d6d7..9a5d3f1d0 100644 Binary files a/docs/assets/images/img-list-english-example.png and b/docs/assets/images/img-list-english-example.png differ diff --git a/docs/assets/images/img-list-german-colors.png b/docs/assets/images/img-list-german-colors.png new file mode 100644 index 000000000..325f19c42 Binary files /dev/null and b/docs/assets/images/img-list-german-colors.png differ diff --git a/docs/assets/images/img-list-german-example.png b/docs/assets/images/img-list-german-example.png index fc1d7d131..fd0091f45 100644 Binary files a/docs/assets/images/img-list-german-example.png and b/docs/assets/images/img-list-german-example.png differ diff --git a/docs/assets/templates/description_en.xlsx b/docs/assets/templates/description_en.xlsx deleted file mode 100644 index 09e624ed6..000000000 Binary files a/docs/assets/templates/description_en.xlsx and /dev/null differ diff --git a/docs/assets/templates/lists/de.xlsx b/docs/assets/templates/lists/de.xlsx new file mode 100644 index 000000000..aa5f90804 Binary files /dev/null and b/docs/assets/templates/lists/de.xlsx differ diff --git a/docs/assets/templates/lists/en.xlsx b/docs/assets/templates/lists/en.xlsx new file mode 100644 index 000000000..86da56ca2 Binary files /dev/null and b/docs/assets/templates/lists/en.xlsx differ diff --git a/docs/dsp-tools-create.md b/docs/dsp-tools-create.md index 6748a7e78..d6270eead 100644 --- a/docs/dsp-tools-create.md +++ b/docs/dsp-tools-create.md @@ -14,6 +14,8 @@ This documentation is divided into two parts: - Overview of the project description file (this page) - The "ontologies" section [explained in detail](./dsp-tools-create-ontologies.md) + + ## A short overview A complete project definition looks like this: @@ -51,6 +53,8 @@ A complete project definition looks like this: } ``` + + ### "prefixes" object (optional) @@ -75,6 +79,8 @@ It is not necessary to define prefixes for the ontologies that are defined in th file can be referenced by their name. See [this section](./dsp-tools-create-ontologies.md#referencing-ontologies) for more information about referencing ontologies. + + ### "$schema" object (required) @@ -83,6 +89,8 @@ The `$schema` object refers to the JSON schema for DSP data model definitions an `"$schema": "https://raw.githubusercontent.com/dasch-swiss/dsp-tools/main/knora/dsplib/schemas/ontology.json"` + + ### "project" object (required) @@ -137,10 +145,14 @@ A simple example definition of the `project` object looks like this: } ``` + + ## "project" object in detail In the following section all fields of the `project` object are explained in detail. + + ### Shortcode (required) @@ -149,6 +161,8 @@ In the following section all fields of the `project` object are explained in det The shortcode has to be unique and is represented by a 4 digit hexadecimal string. The shortcode has to be provided by the DaSCH. + + ### Shortname (required) @@ -158,6 +172,8 @@ The shortcode has to be unique and is represented by a 4 digit hexadecimal strin The shortname has to be unique. It should be in the form of a [xsd:NCNAME](https://www.w3.org/TR/xmlschema11-2/#NCName). This means a string without blanks or special characters but `-` and `_` are allowed (although not as first character). + + ### Longname (required) @@ -166,6 +182,8 @@ string without blanks or special characters but `-` and `_` are allowed (althoug The longname is a string that provides the full name of the project. + + ### Descriptions (required) @@ -175,6 +193,8 @@ The longname is a string that provides the full name of the project. The description is represented as a collection of strings with language tags (currently "en", "de", "fr", "it", and "rm" are supported). It is the description of the project. + + ### Keywords (required) @@ -183,174 +203,246 @@ supported). It is the description of the project. Keywords are represented as an array of strings and are used to describe and/or tag the project. + + ### Lists (optional) `"lists": [,,...]` -Lists can be used to provide controlled vocabularies and can be "flat" or "hierarchical". One advantage of the use of +Lists can be used to provide controlled vocabularies. They can be flat or hierarchical. One advantage of the use of hierarchical lists is that it allows a user to sub-categorize objects. This helps in the formulation of specific search requests. If there is a list node "Vocal music" and sub-nodes "Song" and "Opera", a search for "Vocal Music" would return objects classified as "Song" and "Opera". But a search for "Song" would only return objects classified as "Song". + +The "lists" section is an array of list definitions. A list definition has one root node whose name is used to identify +the list. The children of the root node are the list nodes. If the list is hierarchical, the list nodes can have +children, and these children can again have children etc. -In dsp-tools the structure of a list is mapped using JSON. Only a single root node is allowed which also contains the -name of the list. Inside the root node any number of child nodes and sub-nodes of child nodes are allowed. - -A resource can be assigned to a list node within its properties. For example, a resource of type "Musical work" with the -title "La Traviata" would have a property like "hasMusicGenre" with the value "Grand opera". Within DSP, each property -has a cardinality. Sometimes, a taxonomy allows an object to belong to multiple categories. In these cases, a -cardinality greater than 1 has to be used. +When a list is defined for a project, its values can be referenced in resources within a list property, e.g. a property with +[object "ListValue"](./dsp-tools-create-ontologies.md#listvalue). A node of a list may have the following elements: -- _name_: Name of the node as string. It is mandatory and has to be unique within the list. -- _labels_: Label with language tags in the form `{ "": "