Tizra data records

Tizra data records

A Tizra resource can have many parts to it, and a Tizra resource record can update many of them, except for file/binary content, which must be uploaded via the binary channel (WebDAV).

Meta Types

Every instance of a Tizra object has a type (MetaType). This type system is described in the document modeling documentation.

One currently undocumented feature of the JSON query API is the type-info API call. This will return a list of all the MetaTypes defined for a particular site, and may be useful for you in understanding Tizra metaData (and potentially for checking that definitions exist for all the fields you are interested in).

A typical list of MetaType information.

Fields that occur on all or most objects

The following fields can be part of a resource record when an object is to be updated (note that this is a subset of the information that might be returned from a query on the same object). All objects have fields which are built-in properties of an object that relate to its system functions, and properties (which are keyword-value pairs defined by Tizra types, and always stored in the props field).

• tizra-id A unique Tizra-assigned identifier for an object. immutable
• props This field contains a map of all the values for all properties that have been specified for that object (properties that are defined by the MetaType for that object). No Property is mandatory, and extra properties can be attached to an individual object if necessary. Not mandatory on object creation requests, but creating an object with no properties is not generally useful
• props This is optional, but since it contains all the metadata for an object, it will be present for almost all objects. The MetaType documentation (will have) a complete list of all the system-defined properties that a Tizra object can have.
• url-id This value represents a custom URL component that should be applied to the content on the web site. This string must be unique. This will be the same as the tizra-id if a custom URL has not been set for the object. Setting this to null will remove the custom URL and revert to the default. Interactively, the system will tack numbers onto the end to create an alternate value, but I think that we will want to have a PUT request fail in this instance. Opinions are welcome at this point.
• name This is a name for an object as it would be displayed to the user on a site. In the case of Collections, Virtual Collections and Offers, particularly, the name is often derived by substitution of Freemarker template variables in the Title property of the object. This field is derived from other metadata and never makes sense to specify on an update operation. immutable
• metaType The name identifying the type of object in question. MetaTypes include the definitions and types of all the user-defined properties of an object type, as well as the names of any "Sources" (file storage areas) associated with the object. These areas include document source files, attachments, etc. as described in the document modeling documentation. Individual sites may modify the fields defined for particular metaTypes. When creating a document, this is mandatory
• toc-info This contains the table of contents information for the document. Table of contents information and will be fully described separately. This is delivered as a simple list of entries, each entry marked with its nesting level in the ToC hierarchy.

Associated with each TOC entry is a page index within the document (a 1-based numeration starting at the first page). The pages for successive entries need not be sorted in any way i.e. the table of contents need not be in the same order as the items indexed, so that a table of contents could contain and alphabetized list of illustrations.

Note: There are some redundant field names included in query results for compatibility reasons. These are often camelcase names, but we are moving to the use of hyphenated names in the APIs. Duplicates like urlId and tizraId have been deleted from record examples.

Note: The query interface allows significant bandwidth reduction by filtering of fields and properties. When implmenting JSON queries on page javascripts, make sure to limit the information requested to that needed.

Properties (under props) that occur on all or most objects

• Title The title of a publication.
• Authors list of the authors of a publication. (semicolon separated, with semicolons in values URL-escaped if present).
• AdminTags hidden tags for administrative purposes, usually used to determine collection membership, etc.
• Keywords user-visible keywords that can be used similarly to AdminTags +Abstract An abstract for the publication

Special Properties (props)

Certain properties have built-in system meanings for display and download generation:

+BypassToC is a boolean field. If true, suppresses the table of contents for a book, if false, it is displayed. +AllowPDFDownload is a boolean field. If true, any excerpts will be available for download as separate PDFs. +UserSetVisibility used in access control, can be ignored.

##Document Example

Here's an example of a record describing a document.

{
	"url-id": "King_Richard_III",
	"name": "King Richard III",
	"tizra-id": "36gt2v",
	"props": {
		"BypassToC": false,
		"Abstract": "",
		"CoverImage": "\/King_Richard_III\/~~Attachments\/attachments\/cover.jpg",
		"Authors": "William Shakespeare",
		"AdminTags": "",
		"Keywords": ["assessment", "XMP", "metadata"],
		"AllowPDFDownload": true,
		"Status": "",
		"Title": "King Richard III"
	},
	"meta-type": "Book"
}

Many updates will only consist of a props field, and potentially ToC information.

Excerpt

{
	"tizra-id": "36s8el",
	"url-id": "36s8el",
	"name": "ACT V",
	"props": {
		"Title": "ACT V",
		"Location": "",
		"BypassToC": "true"
	},
	"metaType": "PageRange",
	"pages": [87, 100],
	"range-expression": "87-100",
	"parent": {
		"tizra-id": "36gt2v",
		"url-id": "King_Richard_III",
		"name": "King Richard III",
		"props": {
			"BypassToC": "false",
			"Authors": "William Shakespeare",
			"AdminTags": "",
			"Keywords": "assessment;XMP  metadata  schema XML RDF",
			"AllowPDFDownload": true,
			"Status": "",
			"Title": "King Richard III"
		},
		"metaType": "Book"
	},
}

Fields

• range-expression A character string defining the extent of an excerpt. composed of a comma-separated list of single page numbers or hyphen-separated ranges of page numbers.
• pages an array of integer pairs representing the page numbers included in an excerpt. for instance [1,1,5,7] would represent the result of parsing "1,5-7".
• parent The contents of this field is a complete record representing the information about the document that this excerpt was derived from. On an update (PUT) operation, only the tizra-id of the parent will be used (to identify the parent document).

Collection