-
Notifications
You must be signed in to change notification settings - Fork 4
dsp index
Describo comes with a pre-defined, so called default profile that anyone can use to get started describing their research data. However, if you find that your domain requires properties not defined in the default or you want to limit incoming data to controlled vocabularies then you should consider developing your own profile. This document explains how to do that.
A describo profile is a simple JSON document that tells Describo how to behave. Describo comes with two profiles built in - the default profile and the PARADISEC profile - that can be viewed along with this documentation.
The basic structure of the profile is as follows:
{
metadata: {
name: {A descriptive name for this profile},
version: {the version of this profile - it can be anything that makes sense to your community},
},
items: {
},
typeDefinitions: {
},
enabledCoreTypes: [],
dataPacks: [],
mappings: {}
}
The items section is an object which defines what can be described. If your domain works with Objects and Collections this is where you define the data you wish to capture for those items. For example:
{
...
items: {
Object: {
metadata: {
about: {A short statement describing this item},
allowAdditionalProperties: [ true | false ]
},
inputs: [
... an array of objects that describe each input ...
]
},
Collection: {
}
}
...
}
Each item must have metadata and inputs properties.
-
The metadata property must be an object with two properties:
aboutandallowAdditionalProperties.-
about: this should be a short description explaining this item -
allowAdditionalProperties: Boolean true or false. When loading an ro-crate into Describo, if it contains properties that are not defined in this profile they will be included (true) or excluded (false) based on the value of this property. This is a way to ensure that Describo only considers the properties described in the profile and not others it may encounter when loading a pre-existing ro-crate.
-
-
The input property must be an array of objects where each object describes one property of the profile. This is documented in detail in the section Input Definition.
The typeDefinitions section allows the writer of the profile to define data types that are not part of the Describo default bundle. The keys of this section should correspond to a core schema.org entity type (e.g. Person or Organization) and it must be an object with properties metadata and inputs.
The metadata property is an object with the following properties:
-
allowAdditionalTypes: same meaning as previously defined. -
mapToType: This is a way to limit the data input by the user but still produce a valid output. Consider theGeoShapeclass. It has properties forbox,line, etc. However, maybe you only want a value for theboxproperty from your users. In that case, define a typeGeoBox(though you can call it anything that makes sense) and setmapToType = GeoShape. When Describo loads the interface the user will see aGeoBoxtype with oneboxproperty but when the data is written out the type will be set toGeoShapeas defined in the mapToType property.
The inputs property is an array of objects where each object describes one property of the profile.
In Describo the @id property is special so don't define it in any of your type definitions (it will be ignore anyway). Users will be presented with the ability to define the @id where it makes sense automatically.
In some instances you may wish to provide your own type definition that overrides an inbuilt core entity type like Person. Providing a Person entry in your typeDefinitions object will result in Describo using that Person definition in preference to the inbuilt definition. In this way, you can define the properties for a type that are sensible for your domain if the inbuilt type is not appropriate.
If you wish to limit the user to selecting from a defined vocabulary you can provide a type definition without an inputs property and Describo will provide a lookup to the data packs for entries of that type.
This also works for overriding in built core types. If you don't want users to create specific data type instances but only load them from a pre-defined set then override the type in the typeDefinitions object but don't specify any inputs for it.
Describo comes with definitions for a number of core entities pre-defined. These can be seen @ https://github.com/UTS-eResearch/describo/tree/master/src/components/profiles/types. By default, all of these types will be available within describo. However, for a given domain you may only want some of them. In that case you can define which of the core types should be enabled with this property.
So, if you wanted to only allow the definition of Person and Organization you would set:
...
enabledCoreTypes: [ "Person", "Organization" ]
This set would be joined in to any custom type definitions defined in your profile.
the dataPacks property must be an array of publically accessible URL's from which to load pre-defined
JSON-LD objects for use with the profile. For example, rather than having users define their own language
data we can pre-generate language information from authoritative sources and make them accessible to the user via a data pack. The section Data Packs describes this in more detail.
Internally, Describo maps items with @type arrays to a singular type. If the internal mappings don't suit your data then provide your own:
mappings: {
"File, ImageObject": "File",
"File, SoftwareSourceCode, Workflow": "Workflow",
"File, ImageObject, WorkflowSketch": "WorkflowSketch",
"File, Script, SoftwareSourceCode": "Script",
};
The property is the stringified and sorted values and the value is the type to use internally.
Definining the inputs for a profile item or a type definition is described on the page Input Definition
Creating a data pack is described on the page Data Packs