Categories are used in items and annotations to add structured data to articles. They are stored in the properties table and each category system is configured as a separate property type.
There are four types of properties:
- Properties used in articles and annotations.
- Meta-properties used to categorize other properties in their
properties_idfield. - Properties used as categories to structure the tree, they are flagged in the
iscategoryfield. - See-references establishing an edge between a source and a target property across the tree by using the
related_idfield.
Configuration options
The configuration for each property type includes the following keys:
| Key | Description |
|---|---|
| fields | A list of field configuration objects. See the field configuration documentation for further details. |
| columns | Optional. A list of column configuration objects, keyed by column identifiers. Used for the table view. See the columns configuration documentation for further details. |
| type | Indicates whether the categories form a hierarchy. A tree structure is assumed by default (value ´tree`), you can collapse it (value `collapsed`) or configure a flat list ( value `flat`). For tree structures, in addition, you must configure the parent_id field. |
| displayfield | By default, the `lemma` field should be used as displayfield value. This determines the value, for example, displayed in select lists. Sometimes you have short and long titles for a property. For example, for manageing literature, you store the full bibliographic reference in the `name` field and a short title in the `lemma`. In this case, you can decide to use `name` instead of the `lemma` as your `displayfield`. Alternatively, if a category system is organisized hierarchically, you can use the full path including ancestor lemma values by using `path` as `displayfield` value. |
| caption | The label displayed, for example, in select lists is determined by the displayfield options.
You can output more complex labels by using placeholder keys in the caption value.
For example, you can use the following caption value to display the path and the unit of a property:
"caption": "{path} ({unit})".
|
| level | Optional, experimental. Not all properties in a hierarchical property tree denote the entities used in articles. Some can be used as categories to group its descendants. For example, literature titles could be divided into the categories "Sources", "Archives" and "Literature". You can use the `iscategory` field for each property to clarify the role. In addition, set the `level` key to the first tree level that does not only contain categories. This information may be used in the web interface to style properties by their level. |
| alphasort | Deprecated. Use the sort key instead. |
| edge | Optional. A reference is a subcategory using the `related_id` field to refer to a target property.
This creates a relationship between the parent property and the reference target.
You can use meta-properties to classify different types of relationships, for example,
to capture families using father, mother, daughter, son etc. relationships.
The `edge` configuration object is used to define a displayfield for the reference.
Example to display the lemma of the reference:
"edge": { "displayfield": "lemma" }
Example to display the meta property of the reference:
"edge": { "displayfield": "property.path" }
|
| role | By default, guest users don't see any category systems in the faceted article search. Set the role to `search` to make it available. Alternatively, you can use `index` to indicate that the category system is not only to be used for faceted search, but for indexes in printed publications, if an export stylesheet implements this feature. |
| sort | Although the order is always fixed in the database, properties can be rearranged using mutate operations or in export pipelines. The `sort` value determines the field used for sorting in mutate operations. |
| export | Since the types configuration can be included in exports, you can store additional
data to be used in export stylesheets. Examples:
|
| namespaces | Namespaces used in `norm_data` fields. An object with the namespace prefix as key (e.g. aat) and a namespace configuration object as value.
The namespace configuration object provides the base URL in the baseurl key (e.g. {"baseurl": "http://vocab.getty.edu/page/aat/"}). |
Available fields
Properties include both fields reserved for the Relational Article Model (RAM) and fields that can be customized.
While you can change the labels for all fields, you can only change the data types for customizable fields.
Refer to the format column in the table below to determine whether a field is reserved or customizable.
| Field Key | Formats | Description |
|---|---|---|
| lemma | Customizable: text, xml. Max. 1,500 characters. | The ususal property label. Although you can change the format, it is recommended to use plain text because the value is used widely in the user interface, for example, in select lists. |
| name | Customizable: text, xml. Max. 1,500 characters. | Alternative field for property labels. For example, you can store long bibliographic references in the lemma field and short references in the name field. Although you can change the format, it is recommended to use plain text because the value is used widely in the user interface, for example, in select lists. |
| sortkey | Reserved: text. Max. 1,500 characters. | A string used to sort properties with the mutate function or in export stylesheets. |
| signature | Reserved: text. Max. 1,500 characters. | Usually an identifier within your project, for example the number of a brand. You can reinterpret the field by changing its label, but the type is fixed and cannot be changed. |
| unit | Customizable: text, xml, json. Max. 500 characters. | Usually stores the unit of a value. Example: For properties such as measures, a unit such as "cm". You can customize the field and change the field format for other use cases. |
| content | Customizable: text, json xml. Max. 16,777,215 characters. | Usually contains additional data for a property. You can customize the field and change the field format for other use cases. For example, you could store geolocations of places in JSON format. |
| elements | Customizable: text, json xml. Max. 16,777,215 characters. | Usually contains descriptions about the composition of a property, i.e. if properties denote coat of arms. You can customize the field and change the field format for other use cases. |
| source_from | Customizable: text, json xml. Max. 65,535 characters. | Usually contains information about the the data source Example: A literature reference with further details about the property. You can customize the field and change the field format for other use cases. |
| comment | Customizable: text, json xml. Max. 16,777,215 characters. | Usually contains personal notes about a property. You can customize the field and change the field format for other use cases. |
| keywords | Customizable: text, json xml. Max. 1,500 characters. | Usually contains a short comma-separated list of keywords. Although you can change the format, it is recommended to use plain text because the value is used for keyword filters in the user interface. |
| file_name | Reserved: filename. Max. 1,500 characters. | A file name, for example, to attach an image to a property. |
| parent_id | Reserved: id | Input field for the parent property. |
| related_id | Reserved: id | Reference to another property, for example to identify relationships between persons. The type of reference can be categorized by the lemma or a meta-property (see the `properties_id` field). |
| properties_id | Reserved: id | A meta-property for classifying a property. For example, used to assign a brand type to a brand. Can also be used to provide a relationship type (e.g. "mother of") of references (see the `related_id` field). |
| iscategory | Reserved: check | Usually used to mark a property as structural element in the tree. You can reinterpret the field by changing its label, but the type is fixed and cannot be changed. |
| ishidden | Reserved: check | Usually used to mark a property that should be excluded in published documents. You can reinterpret the field by changing its label, but the type is fixed and cannot be changed. |
| published | Reserved: select | The publication state of the property. 0 = drafted, 1 = in progress, 2 = completed, 3 = published, 4 = searchable. You can reinterpret the field by changing its label, but the type is fixed and cannot be changed. |
| norm_data | Reserved: textM. ax. 65,535 characters. | Authority data, each identifier on one line. You can use namespaces configured in the property type. |
| norm_iri | Reserved: text. Max. 1,500 characters. | IRI fragment of the property. |
| created | Reserved: timestamp. | Timestamp of row creation. |
| modified | Reserved: timestamp. | Timestamp of the last modification. |
| created_by | Reserved: id. | ID of the user who created the row. |
| modified_by | Reserved: id. | ID of the user who last modified the row. |
| id | Reserved: id. | ID of the row. |
Properties implement some virtual fields not present in the database. They are calculated on the fly and can be used in view modes or table columns:
| Field Key | Description |
|---|---|
| ancestors | The list of ancestor nodes. Ususally used together with parent_id. Both can be configured with the same label "Parent lemma", ancestors is used in view mode and parent_id in edit mode to select a parent property. |
| path | The lemma path, including ancestors. |
| iri | The IRI path, consisting of table name, property type and IRI fragment. Usually, used together with norm_iri. While iri generates the full path, norm_iri is used in edit mode to generate an input field for the IRI fragment. |
| image | Displays the file of a property as image. Usually, used together with file_name. While image shows the image, file_name generates an input field in edit mode. |
| articles_count | Number of articles referring to the property. |
| items_count | Number of items referring to the property. |
| links_count | Number of links annotations referring to the property. |