requirements.schema

requirements.schema files specify the minimum requirements your plugin requires to function, and the plugin local schema dictionaries.

Comments are lines beginning with #, lines with no indent start a schema object declaration, and indented lines an value of that schema object.

Where values are multi-value, append [sort=1000] to specify a sort order when requirements from different plugins are merged. The default sort order is 10000.

Because schemas are shared with the user, who can rename things you declare, changing a value in a requirements.schema file won’t change the value. Prefix a value with REMOVE to explicitly remove a value you need to change, but do try to avoid doing this.

When a schema object is declared with as ReadableName, that readable name will be made available in the plugin’s local schema dictionary under that readable name.

A schema object may be declared as OPTIONAL, but you should be quite careful about how you use it.

You can define schema objects in any order in your file.

Requirements generator tool

It’s easiest to create the schema using the system management user interface, then use the built-in schema requirements generator to write your initial requirements.

Your Name » System management » Tools » Generate requirements

You should always trim the generated file down to the minimum requirements. For built in schema objects, this may just be the first line which allows you to use the readable name in your code.

Types

type declarations define types. For example, this declaration defines the standard Book type and makes the type Ref available as T.Book to the plugin.

type std:type:book as Book
    title: Book
    search-name: book
    behaviour physical
    attribute dc:attribute:title [sort=1000]
    attribute dc:attribute:author [sort=1100]
    attribute std:attribute:isbn [sort=1200]
    attribute std:aliased-attribute:year [sort=1300]
    attribute dc:attribute:publisher [sort=1300]
    attribute dc:attribute:subject [sort=1500]
    attribute std:attribute:notes [sort=1600]
    render-type book
    render-icon: E210,1,f
    render-category 0
    label-applicable std:label:common
    create-position normal

Attributes

attribute declarations define attributes which are used in types. This declaraction defines the standard Publisher attribute, and makes the descriptor available as A.Publisher.

attribute dc:attribute:publisher as Publisher
    title: Publisher
    search-name: publisher
    qualifier std:qualifier:null
    data-type link
    linked-type std:type:organisation

Aliased attributes

aliased-attribute declarations define aliased attributes, used on types. This declaraction defines the standard Name alias for Title, using different qualifiers and the person-name data type. It’s made available as AA.Name.

aliased-attribute std:aliased-attribute:name as Name
    title: Name
    search-name: name
    alias-of dc:attribute:title
    on-qualifier std:qualifier:null
    on-qualifier dc:qualifier:alternative
    on-qualifier std:qualifier:nickname
    on-data-type person-name

Qualifiers

qualifier declarations define qualifiers, used on attributes. This declaraction defines the standard Alternative qualifiers, making it available as Q.Alternative.

qualifier dc:qualifier:alternative as Alternative
    title: Alternative
    search-name: alternative

Labels

label declarations define labels, used for the permission system. This declaration defines the standard Confidential label, making it available as Label.Confidential.

label std:label:confidential as Confidential
    title: Confidential
    category Sensitivity
    notes: This item is confidential.

Groups

group declarations define groups, and which other are members of that group. This declaration defines a new group, with another group as a member, and makes the ID available as Group.Example.

group example:group:example as Example
    title: Example group
    member example:group:other

Service users

service-user declarations define service users, which are then used with O.impersonating() within API services to set permissions for those operations. By convention, Service users are created in a pair with a group. Permissions are then set on the group, rather than the service user directly, so the conventions in the code match those for normal users.

group example:group:publisher-service-group
    title: Example Publisher

service-user example:service-user:publisher
    title: Example Publisher Access
    group example:group:publisher-service-group

Objects

object declarations define a generic object with a given type, and a configured behaviour attribute as the given API code. They’re used to set up the default members of a list.

You cannot use as readable names on object declarations. Use the normal store object API, or the Behaviours API.

This declaration ensures that there is a ‘Red’ member of the given list, with a configured behaviour attribute of "example:list:colours:red".

object example:list:colours:red
    type example:type:colours
    title: Red
    notes: This colour is quite nice.

Email templates

email-template declarations define email templates. as readable names cannot be used.

email-template std:email-template:password-recovery
    title: Password recovery
    description: This template is used to send lost password emails.
    purpose: Password recovery

Features

feature declarations define special features, such as the elements on the home page and the left hand navigation.

Schema templates

Sometimes it’s useful to be able to apply requirements to more than one declaration, for example, a set of common attributes that are applied to more than one type.

Define schema templates with a schema-template declaration, then apply the template to other declarations with the apply-schema-template pseudo-value.

schema-template example:schema-template:common-attributes
    attribute std:attribute:project

type example:type:something
    apply-schema-template example:schema-template:common-attributes
    # Other values

Multiple requirements files can add values to the same template.

It is not an error to attempt to apply a template which does not exist.

Type annotations

Sometimes it is useful to work with a set of types, or apply generic functionality to some types without knowing exactly what they are. Type annotations allow you to annotate types with arbitrary strings, and query the schema to find them. You can apply multiple annotations to a type.

type std:type:file
    annotation example:annotation:first
    annotation example:annotation:second

Types with a given annotation are found using SCHEMA.getTypesWithAnnotation(), and SCHEMA.getTypeInfo() to retrieve the annotations on a given type.