diff --git a/docs/dsp-tools-create-ontologies.md b/docs/dsp-tools-create-ontologies.md index a59aca91c..ad3675db9 100644 --- a/docs/dsp-tools-create-ontologies.md +++ b/docs/dsp-tools-create-ontologies.md @@ -1,22 +1,24 @@ # Ontologies -An ontology is a formal representation of a set of terminologies which finally represent real world objects. +An ontology is a formal representation of a set of terms which represent real world objects. Dependencies, attributes and relations of and between the individual components of the set are recorded in a logical, formal language. In contrast to a taxonomy, which defines a mere hierarchical structure within a range of terms, an ontology is much more a network of information of logical dependencies of term elements. Or, in other words, an ontology -defines a strict, formal "data model" for real world _concepts_ such as "Person", "Work", "Artist" etc. - -A full-fledged ontology thus has to offer at least *two* things: a set of _concepts_ or terms (called _resources_, -actually "resource classes") that represent _concepts_ of real world objects, as well as attributes or _properties_ -describing these resources. These properties are linked either to a final value or may define a relationship to another -resource. Let's assume that we define a resource called "Person" and two properties called "hasBirthday" and "hasParent" -. For a specific incarnation of a -"Person" (we call this an _instance_), "hasBirthday" will have a final value such as "1960-05-21", whereas +defines a strict, formal "data model" for real world concepts such as "Person", "Work", "Artist" etc. + +An ontology thus has to offer at least two things: + + - a set of concepts or terms (called **resource classes**) that represent concepts of real world objects + - **properties** describing these resources. These properties are linked either to a final value or may define a + relationship to another resource. + +Let's assume that we define a resource class called "Person" and two properties called "hasBirthday" and "hasParent". +For a specific **instance** of a "Person", "hasBirthday" will have a final value such as "1960-05-21", whereas "hasParent" will link to another instance of a "Person". Within DSP, properties may be re-used for different resources. E.g. a property "description" may be used for a resource called "image" as well as "movie". Therefore, the list of properties is separated from the list of resources. The -properties are assigned to the resources by defining "_cardinalities_". A cardinality indicates if a property is +properties are assigned to the resources by defining "**cardinalities**". A cardinality indicates if a property is mandatory or can be omitted (e.g. if unknown), and if a property may be used several times on the same instance of a resource or not. The cardinality definitions are explained [further below](#cardinalities). @@ -36,10 +38,10 @@ Example of an `ontologies` object: ] }, { - ... + second ontology }, { - ... + third ontology } ] } @@ -108,7 +110,7 @@ A detailed description of `properties` can be found [below](#properties-object-i The resource classes are the primary entities of the data model. They are the actual objects inside a terminology space. A resource class can be seen as a template for the representation of a real object that is represented in the DSP. A -resource class defines properties (_data fields_). For each of these properties a data type as well as the cardinality +resource class defines properties (*data fields*). For each of these properties a data type as well as the cardinality has to be provided. `"resources": [, , ...]` @@ -264,35 +266,42 @@ These three are related as follows: - `gui_element` (required) depends on the value of `object`. - `gui_attributes` (optional) depends on the value of `gui_element`. -The following `object`s are available, and will be discussed below, in this order: - -- `BooleanValue` -- `ColorValue` -- `DateValue` -- `DecimalValue` -- `GeonameValue` -- `IntervalValue` -- `IntValue` -- `ListValue` -- `TextValue` -- `TimeValue` -- `UriValue` -- `Representation` -- in case of the supers `hasLinkTo` or `isPartOf`: any resource class +#### Overview + +| DSP base property (`super`) | `object` | `gui_element` | +|-----------------------------|---------------------------------------------------------------------|--------------------------------------| +| hasValue | BooleanValue | CheckBox | +| hasColor | ColorValue | Colorpicker | +| hasValue | DateValue | Date | +| hasValue | DecimalValue | Slider,
SimpleText | +| hasValue | GeonameValue | Geonames | +| hasValue | IntValue | Spinbox,
SimpleText | +| hasValue | ListValue | Radio, List | +| hasValue | TextValue | SimpleText,
Textarea,
Richtext | +| hasComment | TextValue | SimpleText | +| hasValue | TimeValue | TimeStamp | +| hasValue | UriValue | SimpleText | +| hasLinkTo | (resourceclass) | Searchbox | +| hasRepresentation | Representation | Searchbox | +| isPartOf | (resourceclass) | Searchbox | +| seqnum | IntValue | Spinbox,
SimpleText | +| isSequenceOf | (AudioRepresentation,
MovingImageRepresentation,
or subclass) | Searchbox | +| hasSequenceBounds | IntervalValue | Interval | #### BooleanValue `"object": "BooleanValue"` -Represents a Boolean ("true" or "false). +Represents a Boolean ("true" or "false"). See the [xmlupload documentation](./dsp-tools-xmlupload.md#boolean-prop) +for more information. -*gui-elements / gui_attributes*: +*gui_elements / gui_attributes*: -- `Checkbox`: A GUI element for _BooleanValue_. - - _gui_attributes_: No attributes +- `Checkbox`: The only GUI element for boolean values: a box to check or uncheck + - *gui_attributes*: No attributes -*Example:* +Example: ```json { @@ -313,15 +322,16 @@ Represents a Boolean ("true" or "false). `"object": "ColorValue"` -A string representation of the color in the hexadecimal form e.g. "#ff8000". +A string representation of a color in the hexadecimal form. See the +[xmlupload documentation](./dsp-tools-xmlupload.md#color-prop) for more information. -*gui-elements / gui_attributes*: +*gui_elements / gui_attributes*: -- `Colorpicker`: The only GUI element for _ColorValue_. It's used to choose a color. - - _gui_attributes_: +- `Colorpicker`: The only GUI element for colors. It's used to choose a color. + - *gui_attributes*: - `ncolors=integer` (optional): Number of colors the color picker should present. -*Example:* +Example: ```json { @@ -341,28 +351,16 @@ A string representation of the color in the hexadecimal form e.g. "#ff8000". #### DateValue `object": "DateValue"` -Represents a date. It's a string with the format `calendar:start:end` -Please note that the DateValue is an extremely flexible data type. It can represent an exact date or a date with a given -uncertainty, and the date can be given in several calendars (currently the Gregorian and the Julian calendars are -supported, with the Jewish and Islamic coming soon). Internally, a date is always represented as a start and end date. -If start and end date match, it's an exact date. A value like "1893" will automatically be expanded to a range from -January 1st 1893 to December 31st 1893. - -- _calendar_ is either _GREGORIAN_ or _JULIAN_ -- _start_ has the form _yyyy_-_mm_-_dd_. If only the year is given, the precision is to the year. If only the year and - month is given, the precision is to the month. -- _end_ is optional if the date represents a clearly defined period or uncertainty. - -In total, a DateValue has the following form: "GREGORIAN:1925:1927-03-22" -which means anytime in between 1925 and the 22nd March 1927. +Represents a date. It's a string with the format `calendar:start:end`. See the +[xmlupload documentation](./dsp-tools-xmlupload.md#date-prop) for more information. *gui_elements / gui_attributes*: -- `Date`: The only GUI element for _DateValue_. A date picker gui. - - _gui_attributes_: No attributes +- `Date`: The only GUI element for *DateValue*. A date picker GUI. + - *gui_attributes*: No attributes -*Example:* +Example: ```json { @@ -383,21 +381,21 @@ which means anytime in between 1925 and the 22nd March 1927. `"object": "DecimalValue"` -A number with decimal point. +A number with decimal point. See the [xmlupload documentation](./dsp-tools-xmlupload.md#decimal-prop) for more +information. -*gui-elements / gui_attributes*: +*gui_elements / gui_attributes*: -- `Slider`: A GUI element for _DecimalValue_. Provides a slider to select a decimal value. - - _gui_attributes_: +- `Slider`: Provides a slider to select a decimal value. + - *gui_attributes*: - `max=decimal` (mandatory): maximal value - `min=decimal` (mandatory): minimal value -- `SimpleText`: A GUI element for _TextValue_. A simple text entry box (one line only). The attributes - "maxlength=integer" and "size=integer" are optional. - - _gui_attributes_: +- `SimpleText`: A simple text entry box (one line only). + - *gui_attributes*: - `maxlength=integer` (optional): maximum number of characters accepted - `size=integer` (optional): size of the input field -*Example:* +Example: ```json { @@ -420,16 +418,18 @@ A number with decimal point. #### GeonameValue -Represents a location ID in geonames.org. DSP uses identifiers provided by -[geonames.org](https://geonames.orgs) to identify geographical locations. +`"object": "GeonameValue"` -*gui-elements / gui_attributes*: +Represents a location ID of [geonames.org](https://geonames.org). See the +[xmlupload documentation](./dsp-tools-xmlupload.md#geoname-prop) for more information. -- `Geonames`: The only valid GUI element for _GeonameValue_. It interfaces are with geonames.org and it allows to select - a location. - - _gui_attributes_: No attributes +*gui_elements / gui_attributes*: + +- `Geonames`: The only GUI element for *GeonameValue*. A dropdown to select a geonames.org location, either by ID if + digits are typed in, or by name if letters are typed in. + - *gui_attributes*: No attributes -*Example:* +Example: ```json { @@ -446,65 +446,24 @@ Represents a location ID in geonames.org. DSP uses identifiers provided by ``` -#### IntervalValue - -`"object": "IntervalValue"` - -This `object` belongs to the DSP base property `super: hasSequenceBounds`. It represents a time interval of an -audio or video. It can be used together with an `isSequenceOf` property on a resource that represents the sequence. The -`isSequenceOf` would then point to the audio/video resource, and the `hasSequenceBounds` would be the time interval of -the sequence. - -See the [`isSequenceOf` property](#issequenceof-property) for more detailed explanations. - -*gui-elements / gui_attributes*: - -- `SimpleText`: A GUI element for _TextValue_. A simple text entry box (one line only). The attributes - "maxlength=integer" and "size=integer" are optional. - - _gui_attributes_: - - `maxlength=integer` (optional): The maximum number of characters accepted - - `size=integer` (optional): The size of the input field -- `Interval`: Two spin boxes, one for each decimal - - _gui_attributes_: No attributes - -*Example:* - -```json -{ - "name": "hasBounds", - "super": [ - "hasSequenceBounds" - ], - "subject": ":AudioSequence", - "object": "IntervalValue", - "labels": { - "en": "Interval defining the start and end point of a sequence of an audio or video file" - }, - "gui_element": "Interval" -} -``` - - #### IntValue `"object": "IntValue"` -Represents an integer value. +Represents an integer value. See the [xmlupload documentation](./dsp-tools-xmlupload.md#integer-prop) for more information. -*gui-elements / gui_attributes*: +*gui_elements / gui_attributes*: -- `SimpleText`: A GUI element for _TextValue_. A simple text entry box (one line only). The attributes - "maxlength=integer" and "size=integer" are optional. - - _gui_attributes_: - - `maxlength=integer` (optional): The maximum number of characters accepted - - `size=integer` (optional): The size of the input field -- `Spinbox`: A GUI element for _IntegerValue_. A text field with and "up"- and "down"-button for increment/decrement. - The attributes "max=decimal" and "min=decimal" are optional. - - _gui_attributes_: +- `Spinbox`: A GUI element for *IntegerValue*. A text field with and an "up" and a "down" button for increment/decrement. + - *gui_attributes*: - `max=decimal` (optional): Maximal value - `min=decimal` (optional): Minimal value +- `SimpleText`: A simple text entry box (one line only). + - *gui_attributes*: + - `maxlength=integer` (optional): The maximum number of characters accepted + - `size=integer` (optional): The size of the input field -*Example:* +Example: ```json { @@ -529,19 +488,20 @@ Represents an integer value. `"object": "ListValue"` -Represents a node of a (possibly hierarchical) list +Represents a node of a (possibly hierarchical) list. See the [xmlupload documentation](./dsp-tools-xmlupload.md#list-prop) +for more information. -*gui-elements / gui_attributes*: +*gui_elements / gui_attributes*: -- `Radio`: A GUI element for _ListValue_. A set of radio buttons. This works only with flat lists. - - _gui_attributes_: - - `hlist=` (required): The reference of a [list](./dsp-tools-create.md#lists) root node -- `List`: A GUI element for _ListValue_. A list of values to select one from. This GUI element should be chosen for +- `Radio`: A GUI element for *ListValue*. A set of radio buttons. This works only with flat lists. + - *gui_attributes*: + - `hlist=` (required): The name of a list defined in the ["lists" section](./dsp-tools-create.md#lists). +- `List`: A GUI element for *ListValue*. A dropdown to select a list node. This GUI element should be chosen for hierarchical lists or flat lists that could be expanded to hierarchical lists in the future. - - _gui_attributes_: - - `hlist=` (required): The reference of a [list](./dsp-tools-create.md#lists) root node + - *gui_attributes*: + - `hlist=` (required): The name of a list defined in the ["lists" section](./dsp-tools-create.md#lists). -*Example:* +Example: ```json { @@ -565,24 +525,25 @@ Represents a node of a (possibly hierarchical) list `"object": "TextValue"` -Represents a text that may contain standoff markup. +Represents a text that may contain standoff markup. See the [xmlupload documentation](./dsp-tools-xmlupload.md#text-prop) +for more information. *gui_elements / gui_attributes*: -- `SimpleText`: A GUI element for _TextValue_. A simple text entry box (one line only). The attributes are: - - _gui_attributes_: +- `SimpleText`: A simple text entry box (one line only) + - *gui_attributes*: - `maxlength=integer` (optional): maximal length (number of characters accepted) - `size=integer` (optional): size (width) of widget -- `Textarea`: A GUI element for _TextValue_. Presents a multiline text entry box. The optional attributes are: - - _gui_attributes_: +- `Textarea`: A multiline text entry box + - *gui_attributes*: - `cols=integer` (optional): number of columns of the textarea - `rows=integer` (optional): number of rows of the textarea - - `width=percent` (optional): width of the textarea on screen + - `width=percent` (optional): width of the textarea on the screen - `wrap=soft|hard` (optional): wrapping of text -- `Richtext`: A GUI element for _TextValue_. Provides a richtext editor. - - _gui_attributes_: No attributes +- `Richtext`: A rich-text editor. + - *gui_attributes*: No attributes -*Example:* +Example: ```json { @@ -603,18 +564,44 @@ Represents a text that may contain standoff markup. ``` +#### hasComment property + +`"object": "TextValue"` + +This property is actually very similar to a simple text field. + +Example: + +```json +{ + "name": "hasComment", + "super": [ + "hasComment" + ], + "object": "TextValue", + "labels": { + "de": "Kommentar", + "en": "Comment", + "fr": "Commentaire" + }, + "gui_element": "SimpleText" +} +``` + + #### TimeValue `"object": "TimeValue"` -A time value represents a precise moment in time in the Gregorian calendar. Since nanosecond precision can be included, it is suitable for use as a timestamp. +A time value represents a precise moment in time in the Gregorian calendar. See the +[xmlupload documentation](./dsp-tools-xmlupload.md#time-prop) for more information. -*gui-elements / gui_attributes*: +*gui_elements / gui_attributes*: -- `TimeStamp`: A GUI element for _TimeValue_ which contains a date picker and a time picker. - - _gui_attributes_: No attributes +- `TimeStamp`: A GUI element for *TimeValue* which contains a date picker and a time picker. + - *gui_attributes*: No attributes -*Example:* +Example: ```json { @@ -635,17 +622,16 @@ A time value represents a precise moment in time in the Gregorian calendar. Sinc `"object": "UriValue"` -Represents an URI +Represents an URI. See the [xmlupload documentation](./dsp-tools-xmlupload.md#uri-prop) for more information. -*gui-elements / gui_attributes*: +*gui_elements / gui_attributes*: -- `SimpleText`: A GUI element for _TextValue_. A simple text entry box (one line only). The attributes - "maxlength=integer" and "size=integer" are optional. - - _gui_attributes_: +- `SimpleText`: A simple text entry box (one line only). + - *gui_attributes*: - `maxlength=integer` (optional): The maximum number of characters accepted - `size=integer` (optional): The size of the input field -*Example:* +Example: ```json { @@ -666,44 +652,17 @@ Represents an URI ``` -#### Representation - -`"object": "Representation"` - -A property pointing to a `knora-base:Representation`. Has to be used in combination with `"super": ["hasRepresentation"]`. A resource having this generic property `hasRepresentation` can point to any type of Representation, be it a `StillImageRepresentation`, an `AudioRepresentation`, etc. - -*gui-elements / gui_attributes*: - -- `Searchbox`: Allows searching resources that have super class `Representation` by entering at least 3 characters into - a searchbox. - - _gui_attributes_: - - `numprops=integer` (optional): While dynamically displaying the search result, the number of properties that - should be displayed. - -*Example:* - -```json -{ - "name": "hasRep", - "super": [ - "hasRepresentation" - ], - "object": "Representation", - "labels": { - "en": "Represented by" - }, - "gui_element": "Searchbox" - } -``` +### Link-properties +Link properties do not follow the pattern of the previous data types, because they do not connect to a final value but +to an existing resource. Thus, the `object` denominates the resource class the link will point to. #### hasLinkTo Property -`"object": ""` +`"object": ""` -Link properties do not follow the pattern of the previous data types, because they do not connect to a final value but -to an existing resource. Thus, the `object` denominates the resource class the link will point to. There are different -groups of resource classes that can be the object: +The most basic kind of link property is the `hasLinkTo` property. Its "super" element has to be `hasLinkTo` or derived +from `hasLinkTo`. There are different groups of resource classes that can be the object: - project resources: a resource class defined in the present ontology itself - external resources: a resource class defined in another ontology @@ -713,19 +672,16 @@ groups of resource classes that can be the object: - `Region`: a region in an image - `StillImageRepresentation`, `MovingImageRepresentation`, `TextRepresentation`, `AudioRepresentation`, `DDDRepresentation`, `DocumentRepresentation`, or `ArchiveRepresentation` - - `Representation`: any type of the just mentioned representations. `Representation` is the parent class of them. The syntax how to refer to these different groups of resources is described [here](#referencing-ontologies). -When defining a link property, its "super" element has to be `hasLinkTo` or derived from `hasLinkTo`. +*gui_elements/gui_attributes*: -*gui-elements/gui_attributes*: - -- `Searchbox`: The only GUI element for _hasLinkTo_. Allows searching resources by entering the target resource name. - - _gui_attributes_: +- `Searchbox`: The only GUI element for *hasLinkTo*. Allows searching resources by entering the target resource name. + - *gui_attributes*: - `numprops=integer` (optional): Number of search results to be displayed -*Example:* +Example: ```json { @@ -740,7 +696,45 @@ When defining a link property, its "super" element has to be `hasLinkTo` or deri ``` +#### hasRepresentation Property + +`"object": "Representation"` + +A property pointing to the DSP base resource class `Representation`, which is the parent class of the DSP base resource +classes `StillImageRepresentation`, `AudioRepresentation`, `MovingImageRepresentation`, ... Has to be used in +combination with `"super": ["hasRepresentation"]`. +This generic property can point to any type of the aforementioned representations, or to a subclass of them. See the +[xmlupload documentation](./dsp-tools-xmlupload.md#resptr-prop) for more information. + +*gui_elements / gui_attributes*: + +- `Searchbox`: Allows searching resources that have super class `Representation` by entering at least 3 characters into + a searchbox. + - *gui_attributes*: + - `numprops=integer` (optional): While dynamically displaying the search result, the number of properties that + should be displayed. + +Example: + +```json +{ + "name": "hasRep", + "super": [ + "hasRepresentation" + ], + "object": "Representation", + "labels": { + "en": "Represented by" + }, + "gui_element": "Searchbox" + } +``` + + #### isPartOf Property + +`"object": ""` + A special case of linked resources are resources in a part-whole relation, i.e. resources that are composed of other resources. A `isPartOf` property has to be added to the resource that is part of another resource. In case of resources that are of type `StillImageRepresentation`, an additional property derived from `seqnum` with object `IntValue` @@ -750,13 +744,13 @@ of a book. The DSP base properties `isPartOf` and `seqnum` can be used to derive a custom property from them, or they can be used directly as cardinalities in a resource. The example belows shows both possibilities. -*gui-elements/gui_attributes*: +*gui_elements/gui_attributes*: -- `Searchbox`: The only GUI element for _isPartOf_. Allows searching resources by entering the target resource name. - - _gui_attributes_: +- `Searchbox`: The only GUI element for *isPartOf*. Allows searching resources by entering the target resource name. + - *gui_attributes*: - `numprops=integer` (optional): Number of search results to be displayed -*Example:* +Example: ```json "properties": [ @@ -810,34 +804,31 @@ directly as cardinalities in a resource. The example belows shows both possibili ``` -#### hasComment property +#### seqnum Property -`"object": "TextValue"` +`"object": "IntValue"` -This property is actually very similar to a simple text field. +This property can be attached to a `StillImageRepresentation`, together with `isPartOf`. The `seqnum` is then the page +number of the image inside the compound object. Apart from this, `seqnum` is like an integer property. See the +[xmlupload documentation](./dsp-tools-xmlupload.md#integer-prop) for more information. -*Example:* +*gui_elements / gui_attributes*: -```json -{ - "name": "hasComment", - "super": [ - "hasComment" - ], - "object": "TextValue", - "labels": { - "de": "Kommentar", - "en": "Comment", - "fr": "Commentaire" - }, - "gui_element": "SimpleText" -} -``` +- `Spinbox`: A GUI element for *IntegerValue*. A text field with and an "up" and a "down" button for increment/decrement. + - *gui_attributes*: + - `max=decimal` (optional): Maximal value + - `min=decimal` (optional): Minimal value +- `SimpleText`: A simple text entry box (one line only). + - *gui_attributes*: + - `maxlength=integer` (optional): The maximum number of characters accepted + - `size=integer` (optional): The size of the input field + +Example: See the [isPartOf Property](#ispartof-property) above. -#### isSequenceOf property +#### isSequenceOf Property -`"object": (AudioRepresentation/MovingImageRepresentation or a subclass of one of them)` +`"object": ` This property can be used, together with a `hasSequenceBounds` property, on a resource representing a sequence of an audio/video resource. The `isSequenceOf` would then point to the audio/video resource, and the `hasSequenceBounds` @@ -846,13 +837,13 @@ would be the time interval of the sequence. The DSP base properties `isSequenceOf` and `hasSequenceBounds` can be used to derive a custom property from them, or they can be used directly as cardinalities in a resource. The example below shows both possibilities. -*gui-elements/gui_attributes*: +*gui_elements/gui_attributes*: -- `Searchbox`: The only GUI element for _isSequenceOf_. Allows searching resources by entering the target resource name. - - _gui_attributes_: +- `Searchbox`: The only GUI element for *isSequenceOf*. Allows searching resources by entering the target resource name. + - *gui_attributes*: - `numprops=integer` (optional): Number of search results to be displayed -*Example:* +Example: ```json "properties": [ @@ -908,6 +899,44 @@ they can be used directly as cardinalities in a resource. The example below show ``` +#### hasSequenceBounds Property + +`"object": "IntervalValue"` + +This property represents a time interval of an audio or video. It can be used together with an `isSequenceOf` property +on a resource that represents the sequence. The `isSequenceOf` would then point to the audio/video resource, and the +`hasSequenceBounds` would be the time interval of the sequence, represented as two decimal numbers. + +See the [`isSequenceOf` property](#issequenceof-property) or the +[xmlupload documentation](./dsp-tools-xmlupload.md#interval-prop) for more information. + +*gui_elements / gui_attributes*: + +- `SimpleText`: A simple text entry box (one line only). + - *gui_attributes*: + - `maxlength=integer` (optional): The maximum number of characters accepted + - `size=integer` (optional): The size of the input field +- `Interval`: Two Sliders, one for each decimal + - *gui_attributes*: No attributes + +Example: + +```json +{ + "name": "hasBounds", + "super": [ + "hasSequenceBounds" + ], + "subject": ":AudioSequence", + "object": "IntervalValue", + "labels": { + "en": "Interval defining the start and end point of a sequence of an audio or video file" + }, + "gui_element": "Interval" +} +``` + + ## Resources Object in Detail @@ -964,6 +993,9 @@ used in all cases when your resource is none of the special cases below. - `StillImageRepresentation`: A resource representing an image - `TextRepresentation`: A resource representing a text +**File Extensions**: An overview of the supported file types per representation can be found in the +[xmlupload documentation](./dsp-tools-xmlupload.md#bitstream). + ### Cardinalities diff --git a/docs/dsp-tools-create.md b/docs/dsp-tools-create.md index 3e20116f8..6748a7e78 100644 --- a/docs/dsp-tools-create.md +++ b/docs/dsp-tools-create.md @@ -1,20 +1,22 @@ [![PyPI version](https://badge.fury.io/py/dsp-tools.svg)](https://badge.fury.io/py/dsp-tools) -# JSON data model definition format +# JSON project definition format -This document describes the structure of a data model (ontology) used by DSP. According to Wikipedia, -the [data model](https://en.wikipedia.org/wiki/Data_model) is "an abstract model that organizes elements of data and -standardizes how they relate to one another and to the properties of real-world entities. [...] A data model explicitly -determines the structure of data. Data models are typically specified by a data specialist, data librarian, or a digital -humanities scholar in a data modeling notation". The following sections describe the notation for ontologies in the -context of DSP. +This document describes the structure of a JSON project definition file that can be uploaded to a DSP server. The +command to do so is [documented here](./dsp-tools-usage.md#create-a-project-on-a-dsp-server). -A data model as described in this document can be uploaded to a DSP server. The command to do so is described -[here](./dsp-tools-usage.md#create-a-data-model-on-a-dsp-server). +A project on a DSP server is like a container for data. It defines some basic metadata, the data model(s) and optionally +the user(s) who will be able to access the data. After the creation of a project, data can be uploaded that conforms +with the data model(s). + +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 data model definition for DSP looks like this: +A complete project definition looks like this: ```json { @@ -444,15 +446,15 @@ The `users` element is optional. If not used, it should be omitted. `"ontologies": [, , ...]` -Inside the `ontologies` section all resources and properties are described. A project may have multiple ontologies. It -requires the following data fields: +Inside the `ontologies` section, all resource classes and properties are defined. A project may have multiple +ontologies. It requires the following fields: - `name` - `label` - `properties` - `resources` -A detailed description of `ontologies` can be found [here](dsp-tools-create-ontologies.md) +The `ontologies` section is [documented here](./dsp-tools-create-ontologies.md) ## Fully fleshed out example ontology diff --git a/docs/dsp-tools-excel.md b/docs/dsp-tools-excel.md index 526088de5..8f8c7c5e3 100644 --- a/docs/dsp-tools-excel.md +++ b/docs/dsp-tools-excel.md @@ -104,7 +104,7 @@ Only Excel files with file extension `.xlsx` are considered. All Excel files hav When calling the `excel` command, this folder is provided as an argument to the call. The language of the labels has to be provided in the Excel file's file name after an underline and before the file extension, e.g. `Beschreibung_de.xlsx` would be considered a list with German (`de`) labels, `description_en.xlsx` a list with -English (`en`) labels. The language has to be one of {de, en, fr, it}. +English (`en`) labels. The language has to be one of {de, en, fr, it, rm}. The following example shows how to create a JSON list from two Excel files which are in a directory called `listfolder`. The output is written to the file `list.json`. diff --git a/docs/dsp-tools-usage.md b/docs/dsp-tools-usage.md index c3df150b4..2342c4255 100644 --- a/docs/dsp-tools-usage.md +++ b/docs/dsp-tools-usage.md @@ -24,10 +24,10 @@ pip3 install --upgrade dsp-tools -## Create a data model on a DSP server +## Create a project on a DSP server ```bash -dsp-tools create [options] data_model_definition.json +dsp-tools create [options] project_definition.json ``` The following options are available: @@ -40,21 +40,20 @@ The following options are available: - `-v` | `--verbose`: If set, more information about the progress is printed to the console. - `-d` | `--dump`: If set, dump test files for DSP-API requests. -The command is used to read the definition of a data model (provided in a JSON file) and create it on the DSP server. -The following example shows how to load the ontology defined in `data_model_definition.json` onto the DSP -server `https://api.dsl.server.org` provided with the `-s` option. The username `root@example.com` and the password -`test` are used. +The command is used to read the definition of a project with its data model(s) (provided in a JSON file) and create it +on the DSP server. The following example shows how to upload the project defined in `project_definition.json` to the DSP +server `https://admin.dasch.swiss`: ```bash -dsp-tools create -s https://api.dsl.server.org -u root@example.com -p test data_model_definition.json +dsp-tools create -s https://api.dasch.swiss -u root@example.com -p test project_definition.json ``` -The description of the expected JSON format can be found [here](./dsp-tools-create.md). +The expected JSON format is [documented here](./dsp-tools-create.md). -## Get a data model from a DSP server +## Get a project from a DSP server ```bash dsp-tools get [options] output_file.json @@ -69,16 +68,15 @@ The following options are available: [IRI](https://en.wikipedia.org/wiki/Internationalized_Resource_Identifier) of the project (mandatory) - `-v` | `--verbose`: If set, some information about the progress is printed to the console. -The command is used to get the definition of a data model from a DSP server and write it into a JSON file. This JSON -file could then be used to upload the data model to another DSP server. The following example shows how to get the data -model from a DSP server `https://test.dasch.swiss` provided with the `-s` option. The username `root@example.com` and -the password `test` are used. The data model is saved into the output file `output_file.json`. +The command is used to get the definition of a project with its data model(s) from a DSP server and write it into a JSON +file. This JSON file can then be used to create the same project on another DSP server. The following example shows how +to get a project from the DSP server `https://admin.dasch.swiss`. ```bash -dsp-tools get -s https://api.test.dasch.swiss -u root@example.com -p test -P my_project output_file.json +dsp-tools get -s https://api.dasch.swiss -u root@example.com -p test -P my_project output_file.json ``` -The description of the JSON format can be found [here](./dsp-tools-create.md). +The expected JSON format is [documented here](./dsp-tools-create.md). @@ -101,16 +99,13 @@ The following options are available: - `-v` | `--verbose`: If set, more information about the uploaded resources is printed to the console. The command is used to upload data defined in an XML file onto a DSP server. The following example shows how to upload -data from an XML file `xml_data_file.xml` onto the DSP server `https://api.dsl.server.org` provided with the `-s` -option. The username `root@example.com` and the password `test` are used. The interface for the SIPI IIIF server is -provided with the `-S` -option (`https://iiif.dsl.server.org`). +data from the XML file `xml_data_file.xml` to the DSP server `https://admin.dasch.swiss`: ```bash -dsp-tools xmlupload -s https://api.dsl.server.org -u root@example.com -p test -S https://iiif.dsl.server.org xml_data_file.xml +dsp-tools xmlupload -s https://api.dasch.swiss -u root@example.com -p test -S https://iiif.dasch.swiss xml_data_file.xml ``` -The description of the expected XML format can be found [here](./dsp-tools-xmlupload.md). +The expected XML format is [documented here](./dsp-tools-xmlupload.md). An internal ID is used in the `` tag of an XML file to reference resources inside the same XML file. Once data is uploaded to DSP, it cannot be referenced by this internal ID anymore. Instead, the resource's IRI has to be used. @@ -144,9 +139,8 @@ The following example shows how to create a JSON list from Excel files in a dire dsp-tools excel lists list.json ``` -The description of the expected Excel format can be found [here](./dsp-tools-create.md#lists-from-excel). More -information about the usage of this command can be -found [here](./dsp-tools-excel.md#create-a-list-from-one-or-several-excel-files). +The expected Excel format is [documented here](./dsp-tools-create.md#lists-from-excel). More information about the usage +of this command can be found [here](./dsp-tools-excel.md#create-a-list-from-one-or-several-excel-files). diff --git a/docs/dsp-tools-xmlupload.md b/docs/dsp-tools-xmlupload.md index 9d369769d..3ceea4dba 100644 --- a/docs/dsp-tools-xmlupload.md +++ b/docs/dsp-tools-xmlupload.md @@ -244,7 +244,6 @@ The following property elements exist: - ``: contains JSON geometry definitions for a region - ``: contains [geonames.org](https://www.geonames.org/) location codes - ``: contains list element labels -- ``: contains [iconclass.org](http://iconclass.org/) codes (not yet implemented) - ``: contains integer values - ``: contains interval values - ``: contains time period values (not yet implemented) @@ -268,13 +267,13 @@ Note: Supported file extensions: | Representation | Supported formats | -| --------------------------- |----------------------------------------| -| `ArchiveRepresentation` | ZIP, TAR, GZ, Z, TAR.GZ, TGZ, GZIP, 7Z | -| `AudioRepresentation` | MP3, MP4, WAV | -| `DocumentRepresentation` | PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX | -| `MovingImageRepresentation` | MP4 | -| `StillImageRepresentation` | JPG, JPEG, PNG, TIF, TIFF, JP2 | -| `TextRepresentation` | TXT, CSV, XML, XSL, XSD | +|-----------------------------|----------------------------------------| +| `ArchiveRepresentation` | ZIP, TAR, GZ, Z, TAR.GZ, TGZ, GZIP, 7Z | +| `AudioRepresentation` | MP3, MP4, WAV | +| `DocumentRepresentation` | PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX | +| `MovingImageRepresentation` | MP4 | +| `StillImageRepresentation` | JPG, JPEG, PNG, TIF, TIFF, JP2 | +| `TextRepresentation` | TXT, CSV, XML, XSL, XSD | For more details, please consult the [API docs](https://docs.dasch.swiss/latest/DSP-API/01-introduction/file-formats/). @@ -373,8 +372,17 @@ calendar:epoch:yyyy-mm-dd:epoch:yyyy-mm-dd - `mm`: month with two digits (optional, e.g. 01, 02, ..., 12) - `dd`: day with two digits (optional, e.g. 01, 02, ..., 31) -If two dates are provided, the date is defined as range between the two dates. If the day is omitted, then the precision -it _month_, if also the month is omitted, the precision is _year_. +Notes: + +- If the day is omitted, then the precision is month, if also the month is omitted, the precision is year. +- Internally, a date is always represented as a start and end date. +- If start and end date match, it's an exact date. +- If start and end date don't match, it's a range. +- If the end date is omitted, it's a range from the earliest possible beginning of the start date to the latest possible + end of the start date. For example: + - "1893" will be expanded to a range from January 1st 1893 to December 31st 1893. + - "1893-01" will be expanded to a range from January 1st 1893 to January 31st 1893. + - "1893-01-01" will be expanded to the exact date January 1st 1893 to January 1st 1893 (technically also a range). Attributes: @@ -510,21 +518,18 @@ Example (city of Vienna): ``` -### <list-prop> +### <integer-prop> -The `` element is used as entry point into a list (list node). List nodes are identified by their `name` -attribute that was given when creating the list nodes (which must be unique within each list!). It must contain at least -one `` element. +The `` element is used for integer values. It must contain at least one `` element. Attributes: - `name`: name of the property as defined in the ontology (required) -- `list`: name of the list as defined in the ontology (required) -#### <list> +#### <integer> -The `` element references a node in a (pull-down or hierarchical) list. +The `` element contains an integer value. Attributes: @@ -534,55 +539,27 @@ Attributes: Example: ```xml - - physics - -``` - - -### <iconclass-prop> (_not yet implemented_) - -The `` element is used for [iconclass.org](http://iconclass.org) ID. It must contain at least one -`` element. - -For example: `92E112` stands -for `(story of) Aurora (Eos); 'Aurora' (Ripa) - infancy, upbringing Aurora · Ripa · air · ancient history · child · classical antiquity · goddess · gods · heaven · history · infancy · mythology · sky · upbringing · youth` - -Attributes: - -- `name`: name of the property as defined in the ontology (required) - - -#### <iconclass> (_not yet implemented_) - -References an [iconclass.org](https://iconclass.org) ID. - -Attributes: - -- `permissions`: Permission ID (optional, but if omitted, users who are lower than a `ProjectAdmin` have no permissions at all, not even view rights) -- `comment`: a comment for this specific value (optional) - -Usage: - -```xml - - 92E112 - + + 4711 + ``` -### <integer-prop> +### <interval-prop> -The `` element is used for integer values. It must contain at least one `` element. +The `` element is used for intervals with a start and an end point on a timeline, e.g. relative to the beginning of an audio or video file. +An `` must contain at least one `` element. Attributes: - `name`: name of the property as defined in the ontology (required) -#### <integer> +#### <interval> -The `` element contains an integer value. +A time interval is represented by plain decimal numbers (=seconds), without a special notation for minutes and hours. +The `` element contains two decimals separated by a colon (`:`). The places before the decimal point are +seconds, and the places after the decimal points are fractions of a second. Attributes: @@ -592,27 +569,28 @@ Attributes: Example: ```xml - - 4711 - + + 60.5:120.5 + 61:3600 + ``` -### <interval-prop> +### <list-prop> -The `` element is used for intervals with a start and an end point on a timeline, e.g. relative to the beginning of an audio or video file. -An `` must contain at least one `` element. +The `` element is used as entry point into a list (list node). List nodes are identified by their `name` +attribute that was given when creating the list nodes (which must be unique within each list!). It must contain at least +one `` element. Attributes: - `name`: name of the property as defined in the ontology (required) +- `list`: name of the list as defined in the ontology (required) -#### <interval> +#### <list> -A time interval is represented by plain decimal numbers (=seconds), without a special notation for minutes and hours. -The `` element contains two decimals separated by a colon (`:`). The places before the decimal point are -seconds, and the places after the decimal points are fractions of a second. +The `` element references a node in a (pull-down or hierarchical) list. Attributes: @@ -622,10 +600,9 @@ Attributes: Example: ```xml - - 60.5:120.5 - 61:3600 - + + physics + ``` @@ -721,7 +698,7 @@ conform to the special format `IRI:[res-id]:IRI` where [res-id] is the resource ### <time-prop> -The `` element is used for time values. It must contain at least one `