Skip to content
This repository has been archived by the owner on Jul 12, 2023. It is now read-only.

dsp input definition

Jump to bottom
Marco La Rosa edited this page Aug 4, 2020 · 4 revisions

Input Definition

Perhaps the most important section for both items and typeDefinitions this is where you define what you want to describe and the type of data that should be collected.

Example input definition

Following is an example input definition that collects a string of text from the user.

 {
     // the schema.org property to write this data against
     property: "name",

     // the label to display - otherwise the last element of property is shown
     label: "Name",

     // the type of element: one of the core types
     "@type": "Text",

     // whether this element is required - used by strict
     required: true,

     // whether Describo should collect multiple entries for this property
     multiple: false,

     // some help text for your users to understand what is required
     help: "A name for this crate.",

     // the group this property belongs to - determines whether the property is always visible
     group: "important",
 },

The common properties are as follows:

  • 'property' (MANDATORY): this can be a simple property like name which is assumed to be https://schema.org/name or a fully qualified name like https://my.domain/ontology/propertyName.
  • label: (OPTIONAL): a label to display instead of the property name.
  • @type: (MANDATORY): the type of data that should be collected for this property.
  • required: (OPTIONAL): Boolen - true | false; whether this field requires data. This tells Describo to highlight the field with a red background when there is no data. This does not stop the user from creating the crate. Rather, it's a visual cue to remind them that some data is required.
  • multiple: (MANDATORY): Boolean - true | false; whether Describo should collect an array of items of this type. If not set it default to true.
  • help: (OPTIONAL): some text to help the user understand what is required of them
  • group: (OPTIONAL): Value - 'important' or not defined; any given schema.org type can have many potential properties. This is a way to specify which of those are important so they are alway visible instead only being available when the users presses the 'show additional properties' button.

Input definition types

Within Describo there are the so called simple input types and the complex types which map to schema.org entities.

The set of simple types is: Text, TextArea, Value, Date and Select. The set of complex types is all of those @ https://github.com/UTS-eResearch/describo/tree/master/src/components/profiles/types along with any typeDefinitions in the profile.

Text

To collect a string of data from the user set '@type' = 'Text' as follows:

{
    property: "description",
    "@type": "TextArea",
},

TextArea

To display a textarea to the user set '@type' = 'TextArea' as follows:

{
    property: "description",
    "@type": "TextArea",
},

Value

If you want to set a specific value for a property set '@type' = 'Value' and provide a value as follows:

{
    property: "additionalType",
    "@type": "Value",
    value: "item",
},

Date

If you want to collect an ISO date for a property set '@type' = 'Date' as follows:

{
    property: "datePublished",
    "@type": "Date",
},

Select

If you want to limit the data collected to a set of options set '@type' = 'Select' and provide an options array of values as follows:

{
    property: "colours",
    label: "Colours",
    "@type": "Select",
    options: ["Red", "Green", "Blue", "Other"],
},

Complex Types

You can state that an input should be a schema.org entity like Person or Organization or both as follows:

{
    property: "description",
    "@type": [ 'Person', 'Organization' ],
},

However - note that you can't mix simple and complex types so the following is not allowed:

{
    property: "description",
    "@type": [ "TextArea", "Person" ],
},

Extending to external vocabularies

You might find that you can't describe your data using only schema.org properties. In that case, you can easily extend your profile with external vocabularies. There are two ways to do this - using properties from an existing ontology or defining your own properties.

Using properties from an existing ontology

Let's say you're documenting a dataset about cows and you need to describe a property that is defined in an external ontology - let's make one up: https://cow.ontologies.com/current/properties.html. Further, let's say we need the property pattern from that ontology which is defined at https://cow.ontologies.com/current/properties.html#pattern . In order to use this property in your input all you need to do is reference it!:

 {
    // the schema.org property to write this data against
    property: "https://cow.ontologies.com/current/properties.html#pattern",

    ... the rest of the input definition as described above ...
  },

When you save the crate describo will ensure that the property definition is put into the context to produce a valid JSON-LD object.

Defining your own properties

Likewise you can define your own properties if you really need to (but try to use existing ontologies where possible!).

Following is the definition of a profile input called orthographicNotes:

{
    "property": "orthographicNotes",
    "@type": "TextArea",
    "multiple": false,
    "group": "important",
    "definition": {
        "@id": "_:orthographicNotes",
        "@type": "Property",
        "name": "orthographicNotes",
        "description": "something or other about data"
    }
},

The profile entry is as described above with one extra property: definition. This definition object must conform to the following requirements:

  • It must have an @id property which matches the pattern: _:{name of property}.
  • It must have an @type property = 'Property'
  • It must have name and description properties where the name = {name of property} and description is the documentation for that property; ie what it means and the type of data expected.
Clone this wiki locally