Property Templates: Types of fields and options for each
To set up a template, you fill in template metdata and configure Property Templates. You'll need one Property Template for every field you want in the form that will be created from this template.
After you open a blank template by clicking the New template button the Resource Templates tab, your blank template has one Property Template. A template must have at least one Property Template configured. In other words, a cataloging form in Sinopia will have at least one field.
To add additional Property Templates to your Template (which you're going to have to do if you want your form to have more than one field!), click +Add another.
Below are instructions for configuring each Property Template.
- Enter the property URI. The property URI you enter here will end up as the property of the RDF statement created by this field when the template is used for cataloging. So if you enter
http://id.loc.gov/ontologies/bibframe/copyrightDatehere, and the cataloger fills in this field with2000, the resulting RDF statement will be<> http://id.loc.gov/ontologies/bibframe/copyrightDate "2000" .where <> is the URI Sinopia will mint for the "thing" that is cataloged. - Sinopia does enforce that the value you enter here is a URI, but Sinopia doesn't enforce that it has to be a valid property for the Class you entered in the template metadata. You can use any property from any ontology. (In fact, Sinopia does not check that it's actually a property at all, just that it's a URI.)
- Property URI is required.
- To give the cataloging user a choice of properties, use the +Add another Property button to add additional property URIs. At cataloging time, Sinopia will present a dropdown of all the property URI choices.
- Important limitation! You cannot re-use a property URI for more than one field, unless both propery templates are of type nested resource and the nested resources are of different classes. (See this page if you want to know more.) A cataloger can repeat a field you set up--this is explained below. Sinopia does not enforce this limitation when you save your template, but the cataloger will get this error message when trying to use a template with more than one field with the same property URI:
A property template may not use the same property URI as another property template (http://www.property.com/p1) unless both propery templates are of type nested resource and the nested resources are of different classes.
- Enter the field name that will appear when this template is used for cataloging.
- Label is required.
- Enter help text for this field.
- Remark is not required.
- Fields that have a remark will be displayed with an "i" icon next to the fieldname. The cataloger can click the "i" icon to see the Remark text. For example, the Name field here was configured with Remark = Enter name as last name, first name.
- If your text includes a URL, it will displayed as a clickable link in the text box.
- If you want to provide a link to a webpage that will give guidance about filling in this field, use Remark URI.
- Remark URI is not required.
- Fields that have a Remark URI will be displayed with an "external link" icon next to the fieldname. The cataloger can click the "external link" icon to visit the Remark URI in their browser.
- If you include both a Remark and a Remark URL, both the "i" icon and the "external link" icon will be displayed.
Optional property attributes are:
- language suppressed: hides the language tagging button so language tagging is not possible (relevant only for property types literal and uri or lookup)
- ordered: adds RDF to keep track of the order of multiple values entered for a field (relevant only for properties with the repeatable attribute selected)
- repeatable: allows cataloger to enter more than one value
- required: the resource cannot be saved unless this field is filled in (relevant only for property types literal and uri or lookup)
If none of these optional attributes is selected, your field:
- will have a language tagging option where appropriate
- will be optional (the cataloger will not be required to fill in the field before saving)
- will not be repeatable (the cataloger will be able to add only one value to this field)
- will not be ordered (if the field is repeatable, the order of the values is not retained and is not significant)
More details:
- For repeatable fields, if you want Sinopia to retain the order of the repeated values, select the "ordered" attribute from the dropdown.
- When the repeated values are saved, Sinopia will use the RDF "first" and "rest" syntax to order the entered values.
- Note that there is currently not an easy way for the cataloger to re-order entered values.
- If you want Sinopia to enforce that a field be filled in during cataloging, select the "required" attribute from the dropdown.
- The field will be displayed with an asterisk, and Sinopia will check that the field is filled in when the cataloger tries to save. In this example, the Name field is required, and if the cataloger tries to Save without filling it in, Sinopia gives an error message.
- Sinopia supports several field types, and here's where you specify what type of field you want. In other words, what kind of object is expected by this property. The types are literal, nested resource, URI, and lookup.
- Property type is required.
Looking at each property type in detail:
- Select "literal" if you expect the cataloger to enter a literal value.
- Select "nested resource" if the object of your field will be "context node". In other words, the object is a node that is itself the subject of some statements. For example, a Work has a Contributor, and the Contributor has a Role. If the Work has more than one Contributor, a flat list of fields can’t express which Role goes with which Contributor. This type of situation is handled by creating a Contribution template containing a Contributor and the Contributor's Role, and then embedding one template in another so that you end up with a set of fields that stays together and works as a unit.
- You'll select which template to nest farther down in the template configuration.
- Note that you can nest a template that has another template nested within it. So you could nest template B in template A, while template B itself nests template C.
- Select "uri or Lookup" for either of two situations: (1) the object of your field should be a URI entered by the cataloger; or (2) the field should be displayed as a lookup for the cataloger to select a URI and label from an external source of URIs (via the Questioning Authority service), or from a search of resources already cataloged in Sinopia. Note that some lookups will be displayed as dropdown lists, as opposed to a searchable authority. The setting of whether an authority is displayed as a dropdown or a search box is made on the backend in Sinopia when a QA authority is added to Sinopia.
The rest of the template configuration involves specifying attributes for the type of property you selected. Note that Sinopia doesn't enforce that you specify the appropriate attributes for your property type. You could fill in URI attributes on a literal property, but you will end up with unexpected results.
The attributes relevant for a literal field (all optional) are
- Defaults
- Validation Regular Expression
- Validation Data Type
- Literal property attributes: date default and user id default
- To give your field a default value, enter it here. When used for cataloging, this field will already be filled in with the default value, which the cataloger can then leave as is or change.
- To restrict a literal field so that the entered value must match a regular expression, a data type, or both, use these attributes. When the template is used for cataloging, help text will tell the user what expression the literal must match, or what data type it must conform to. When a cataloger attempts to save a resource, this field's value will be validated agains the regular expression or data type.
Example where Validation Data Type has been set to EDTF
If you select date default or user ID default here, Sinopia will fill in this field with the current date or the user's ID when the template is opened for cataloging.
- If you chose property type "uri or lookup" and you are expecting a URI in this field, optional attributes are Defaults and Label suppressed (found under the second-level URI attributes field).
- To give your field a default URI and label, enter it here. When used for cataloging, this field will already be filled in with the default value, which the cataloger can then leave as is or change.
- For URI fields where a label is not expected or appropriate, select Label suppressed. The URI field will have a place to fill in a URI, but not a corresponding label.
Lookups must have at least one Authority specified; Defaults are optional.
- If you chose property type "uri or lookup" and you want this field to be displayed as a lookup to an external source of URIs, or a lookup to Sinopia resources, you need to specify what the lookup source is. You do this in "Authorities".
- Sinopia uses the Questioning Authority lookup service. To read more, and see a list of supported authorities, see this page.
- From the dropdown, select the authority you want to use.
- A field can be a lookup to multiple authorities. To select an additional authority, click the dropdown again and select another authority.
- You can also specify a default URI and label for a lookup field. This results in a field with a value already entered, but which also lets the cataloger do a lookup.
- If you chose property type "nested resource", here's where you choose the other template to nest.
- You can nest more than one template here. Example: A Person can have a Home Address and a Work Address. One way to model this is to have a template for class:Person that nests another template for class:Address, and make the Address template repeatable. But if you want each address to be typed with a specific subclass of Address, instead you might make one template for class:WorkAddress and one for class:HomeAddress and then nest them both in the Person template. As always, there's more than one way to do things, and some things you might want to do aren't (yet) possible in Sinopia. (In that case, please open an issue!)
- Caution: In a single nested resource field, you cannot nest two templates with the same class. If you do, you'll get an error when the template is opened.
- In "Resource template ids", search for and select the template you want to nest. This means the template you want to nest has to exist before you can nest it.
- Note: While it's possible to add a default value and/or default URI in a property template with type nested resource, Sinopia ignores those, as a single default value for a nested template does not make sense.
- Another note: While it's possible to select the "required" attribute for a nested resource, it is unclear what this would mean in practice (what is actually required?) and Sinopia ignores this (an asterisk appears seeming to indicate the nested resource is required, but Sinopia does not do any kind of checking).
Short story: there's lots of flexibilty in how you configure things, but Sinopia does not check that you've selected the right attributes for your field type. So if you get unexpected results, check your template again. (There is an open issue relating to showing only the relevant property attributes.)