Resource settings:section

Overview

The settings:section resource is the organizational item which contains this section’s settings and links available (child) sections (settings:sub-sections).

Properties

The settings:section resource has the following properties:

section

sections have no base property because they don’t fulfill the prerequisites, which make them uniquely identifyable in a system’s context. Instead, each section contains a section property, which further contains data, esp. to identify a section in a more "local" context. The sections property contains a JSON object-literal.

settings

A JSON object-literal, which enumerates each setting as a key being associated to yet another JSON object-literal representing the data of an individual setting. See settings description

Common Link Relations

settings:root-section

Provides the resource representing the very root section.

settings:section-by-path

Provides the resource representing the specified section.

settings:parent-section

Provides the current section’s direct parent section.

settings:path (multi-link)

An array of links, which refer to thesections, which are above the hierarchy of the current section.

Description

The "section" Property

A section has no base property because it don’t fulfill the prerequisites, which makes it uniquely identifyable in a system’s context. Instead, each section contains a section property, which further contains data, esp. to identify a section in a more "local" context. The information about a section’s hierarchy is to be picked from settings:path links.

Example:

   "section":{
	"name":"Resolutions"
	"systemType":"interplay-pam",
	"systemID":"bb9d3d06-0e41-419e-8ae7-efdbbcbaa6e0",
	"labels": {
		"en": "A section collecting settings about resolutions"
	}
   }

name

name obviosly represents the name of a section. The name of individual sections are just “local“ names, i.e. they do not unleash the hierarchy above. The information about hierarchy is to be picked from settings:path links.

  • The local name of the root section is represented by "Root" just as a mnemonic.

systemType and systemID

Those just represent systemtype and systemID as a "full" base property would do.

labels

An optional JSON object-literal specifying a bunch of key-value pairs mapping a language tag to a localized label-text. The key must be a valid IETF BCP 47 language tag.

The "settings" Property

"settings" represents a JSON object-literal, which enumerates each setting as a key being associated to yet another JSON object-literal representing the data of an individual setting.

Example: settings property
 
   "settings":{
      "width":{
         "value":"34",
         "description":"The brilliant width setting.",
         "type":"int",
         "range":{
            "from":14,
            "to":50
         },
         "labels": {
            "pl": "Szerokość"
            "en-US": "Width",
            "en-UK": "Width",
            "en": "Width",
            "de": "Breite"
        }
      },
      "colordepth":{
         "value":"8-bit grayscale",
         "description":"also known as bit depth",
         "applies-to-folder":"/Projects/editorsmaterial",
         "applies-to-principal":"/Editors/DailyShow/bill",
      },
      "designercolormodel":{
          "value":"HSB",
          "defaultvalue": "solid",
          "description": "the color model used, e.g. in color pickers",
          "type": "enum",
          "range":{
            "values": ["RGB", "HSB", "HSV", "solid"]
          }
      },
      "colorkeys":{
          "value": ["00FF00", "00FFFF"],
          "type": "string",
          "list": true
      }
   }
 

value

The essential value of the setting.

defaultvalue

An optional default value, which is applied if a setting is deleted and the semantics of the implementation handles deletion as fallback to default .

description

An optional description of the setting.

type

The optional type of the setting (or its list elements, see below). It is recommended to default the type to "string". It can be any of "boolean", "int", "float", "string", "object" or "enum". If the type is "object", value can hold any JSON object-literal.

range

Can be applied for "int", "float" or "enum".

  • The optional range of "int" or "float" settings.

  • The mandatory list of allowed values for an "enum".

labels

An optional JSON object-literal specifying a bunch of key-value pairs mapping a language tag to a localized label-text. The key must be a valid IETF BCP 47 language tag.

flags

An optional array of strings representing flags. The flags highly depend on the respective service and cannot be extensively described here. Some already applied flags are "readonly" and "deletable".

list

If this boolean property is set to true, the belonging to value is interpreted as list, whose individual elements are of type type. The value is then represented as JSON array.

Examples

The section /TranscodingData/Resolutions/ (%2FTranscodingData%2FResolutions%2F)
 
{
   "section":{
      "name":"Resolutions",
      "systemType":"interplay-pam",
      "systemID":"bb9d3d06-0e41-419e-8ae7-efdbbcbaa6e0",
      "labels": {
      	"en": "A section collecting settings about resolutions"
      }
   },
   "settings":{
      "PreferredResolution1":{
         "value":"2k",
         "description":"Primary, preferred resolution",
         "labels": {
            "en": "Primary, preferred resolution"
          }
      },
      "PreferredResolution2":{
         "value":"4k",
         "description":"Secondary, preferred resolution",
         "labels": {
            "en": "Secondary, preferred resolution"
          }
      }
   },
   "_links":{
      "self":{
         "href":"https://host/…​"
      },
      "settings:sub-sections":[
         {
            "href":"https://host/…​",
            "title":"TranscodingDataWorkflow1"
         },
         {
            "href":"https://host/…​",
            "title":"TranscodingDataWorkflow2"
         }
      ],
      "settings:settings":{
         "href":"https://host/…​"
      },
      "settings:path":[
         {
            "href":"https://host/…​",
            "title":"Root"
         },
         {
            "href":"https://host/…​",
            "title":"TranscodingData"
         }
      ],
      "settings:parent-section":{
         "href":"https://host/…​"
      }
   }
}