TextRef is designed with a simple data model enabling data to be both human editable and machine actionable, supporting manual curation of datasets as well as automatic generation.

A TextRef dataset must specify two things:

Each of these is specified using a simple CSV (Comma Separated Value) file. Each CSV file contains a single table of data, and these files can be easily created using spreadsheet software such as Microsoft Excel, as well as any other desired method.

Data model

Each dataset consists of a metadata file and a data file. Both files must be accessible online at a known location specified by URL, and these locations must be recorded in the metadata file as described below. Additionally:

Metadata file

A metadata file consists of two columns of data, labeled "Field" and "Value". Each row specifies a field name (case insensitive) and a value for the corresponding field. Defined fields are as follows:

Field nameValueRequired/optional
MetaURLLocation (as HTTP or HTTPS URL) of this metadata file.Required
DataURLLocation (as HTTP or HTTPS URL) of the corresponding data file.Required
ShortNameA short (max 20 character) title for the dataset.Required
LongNameA longer descriptive title for the dataset.Required
ResourceTemplateTemplate to transform a primary_id value into a URL for a specific resource.Optional
SchemaURLSchema file specifying what format the data file implements.Optional
LicenseLicense applying to the data file. Possible values: "CC 0", "CC BY", "CC BY-SA", "CC BY-NC", "CC BY-NC", "CC BY-NC-SA".Optional

If a value for ResourceTemplate is specified, it must take the form of a URL containing the string "{primary_id}"; this string will be replaced with the primary ID of a specified resource, and the template must be chosen so that this creates a URL resolving to that resource.

Data file

A data file consists of columns of data as described below. Undefined column names are ignored; defined column names are as follows:

Column nameValueRequired/optional
Primary_idA unique (within this data file) identifier for this rowRequired
TitleThe title of the itemRequired
AuthorThe author of the itemRequired
EditionThe edition of the textual objectOptional
CollectionThe title of the collection to which the textual object belongsOptional
Fulltext_ReadResource allows viewing of full-text content*Optional
Fulltext_SearchResource allows full-text search*Optional
Fulltext_DownloadResource allows full-text export/download*Optional
ImageThis resource has online full-text functionality*Optional

* Value should be "y" if present, "n" if not present, left blank if unknown/not specified.