The Codex Metadata Model.

Codex app retired as of Nolana

Please note that as of the Nolana release (Q3 2022) the Codex app was retired - these pages may still reference the app and associated modules.

Codex

Codex is a normalization and virtualization layer that allows Folio to integrate metadata about various resources regardless of format, encoding, or storage location. It is the piece that allows disparate resources to be surfaced using a common vocabulary and description.

The Codex metadata model for Folio is inspired by both the BIBFRAME 2 conceptual model and the Dublin Core (DC) Elements. The conceptual model (objects) are as shown in the following diagram.

The Codex Metadata Model

instance.json	instanceCollection.json
item.json	itemCollection.json
package.json	packageCollection.json
coverage.json	coverageCollection.json
location.json	locationCollection.json

The initial model consists of 5 objects (in orange). It is anticipated that more objects will be added to the model. Some of the future objects are already known (in blue): Work and Subject.

This model is only inspired by BIBFRAME 2, it does not strictly adhere to BIBFRAME2. A key concept is the similar central stack consisting of Work - Instance - Item. Although in this case, which object contains specific properties may differ. This model includes an object not found in BIBFRAME: the Package. The Location and Coverage objects are shown broken out as separate objects. This is to illustrate their reusability for other parts of Folio. They are represented using distinct JSON schema definitions, but in practice they will be found nested within higher level objects such as Item or Package.

Instance

The Instance object represents the generalized abstraction of a resource, Out of necessity this object also takes on some of the properties which BIBFRAME 2 might place in the Work.

The Instance object consists of the following fields.

Field		Type	Required	Repeatable	Description
id		string	Y		The internal id of the Instance record (UUID)
title		string	Y		The primary title (or label) associated with the resource
altTitle		string			An alternative title for the resource. (e.g. original language version title of a Movie)
series		string			A series title associated with the resource (e.g. Harry Potter)
contributor		string		Y	A set of secondary authors/creators tied to the resource
publisher		string			The publisher, or provider, of the resource
date		string			A date associated with the resource (e.g. publication date)
type		string			The resource type. (e.g.: serial; monograph; audio recording; etc..)
format		string			The material type or distribution format of the resource. (e.g.: hardcover; cassette tape; dvd; etc..)
identifier		object		Y	An extensible set of name-value pairs of identifiers associated with the resource
	type	string			identifier type : e.g. ISSN
	value	string			identifier value
source		string			a link back to the source record for this metadata
language		string		Y	the set of languages used by the resource
rights		string			Access rights associated with the resource
version		string			This is where the edition can be found in the case of a monograph
lastModified		string			Adminstrative field indicating date at which the resource was added to the Codex.

Instance JSON schema.

Item / Holding

This objects represents two distinct concepts: (1) an Item in the sense of a specific copy of an Instance; (2) a Holding which describes the relationship of the library or institution to the Item. From a data modeling point of view there is so much overlap in the set of metadata needed to describe them both, that it only makes sense to use a single object to represent both concepts together. The term Item in the rest of this document should be understood to be interchangeable with Item/Holding.

Also note that what is discussed in this document is as a “holding” is slightly different from what is known as a holding in the context of a MARC holdings record (MFHD). In this context, a “holding” represents the possession of (or access to) a resource by the library: what is being held.

The Item represents a specific material copy of an Instance. Put differently, an Item has a single Instance as a parent. The Item will inherit many fields from its parent Instance, which will appear directly within the Item object. If the field changes in the Instance it will be instantly reflected in the corresponding Item field. (Behind the scenes the implementation will share the data rather duplicate it between the two object types.)

There is however the ability to override these inherited fields at the Item level. On the surface, this feature doesn’t make much sense when one thinks of a Codex Item and Instance representing a resource described in the Inventory domain. However, it does make more sense when one considers Referential Cataloging. If the master bibliographic description is being maintained in a system external to Folio, such as in a knowledgebase, there is an expectation that corrections and updates will be made in the external system. Since there is no direct control as to when those may be made, the override allows for a temporary update to be applied by the local library directly and immediately. When the changes are eventually made in the remote system, the local overrides can be removed and the fields will revert to their inherited values which reference the master bibliographic record.

Field		Type	Required	Repeatable	Description
id		string	Y		The internal id of the Item record (UUID)
instanceid		string	Y		Link back to the parent Instance
description		string			Free-form description of the resource
title		string	Y		Inherited from Instance: see above
altTitle		string			Inherited from Instance: see above
series		string			Inherited from Instance: see above
contributor		string		Y	Inherited from Instance: see above
publisher		string			Inherited from Instance: see above
date		string			Inherited from Instance: see above
type		string			Inherited from Instance: see above
format		string			Inherited from Instance: see above
identifier		object		Y	Inherited from Instance: see above
	type	string			Inherited from Instance: see above
	value	string			Inherited from Instance: see above
source		string			Inherited from Instance: see above
language		string		Y	Inherited from Instance: see above
rights		string			Inherited from Instance: see above
copyNumber		number			the "bad old" copy number. Required for backwards compatibilityThe Codex Metadata Model.
barcode		string			barcode on the Item
vendorPackage		string			name of vendor package associated with item. (Not to be confused with the Codex Package object.)
coverage		object			See Coverage object
location		object		Y	See Location object. There can be multiple locations associated with an Item: e.g. Permanent and Termporary
itemStatus		string			Item state: e.g. on order
isSelected		boolean			Holding property. Selection state ("is it held?") of the Item. Mostly relevant for e-resources
isCustomized		boolean			Administrative flag to indicate that inherited fields have been overwritten

Item JSON schema.

Package

The Package represents a container of either Instances and/or Items. As such it provides the ability to group these together for any number of reasons. A given Instance or Item may be placed in any number of Packages since these are ostensibly independent groupings and there are many possible ways to group resources.

The Codex Package should not be confused with the more familiar package object found in a typical electronic resource knowledgebase. The latter is a bundling mechanism used by vendors for commercial purposes. The former is a much broader notion which can be used to represent all sorts of groupings. Obviously, the commercial package from a vendor will find itself represented in the Codes as a Package object of a particular type. However, it is only one of many possible types of Packages.

In addition to being a container of objects, the Package is an object in its own right. It contains a number of metadata fields which are used to describe it, separately from its container payload. The Package object can then be used as a whole to manipulate resources in a very powerful fashion.

Field	Type	Required	Description
id	string	Y	The internal id of the Package record (UUID)
identifier	string		An external identifier used to track the Package (e.g. a barcode)
name	string		A name (or label) associated with the Package
description	string		A free-form description of the Package
type	string		The type of package - what sort of collection does it represent. (e.g. DVD box set; boundwidth; archival cardboard box; etc..)
vendorid	string		Link to vendor object associated with this resource (could be in another domain)
vendor	string		Name of vendor for display purposes
platform	string		Platform hosting the e-resource.
items	array	Y	Array containing Instance or Item objects
itemCount	number		Number of items found in the itemsArray
selectedCount	number		Number of items in the ItemsArray that are selected ("are held"). Mostly relevant for e-resources
coverage	object		Coverage object for the package itself, rather than its contents. See Content object
isSelected	boolean		Selection state ("is it held?") of the package itself, rather than its contents. Mostly relevant for e-resources

Package JSON schema.

Location

The Location object will be typically be found nested within the Item or Package object. However, it warrants its own representation as it is a powerful object with potential reuse in other parts of Folio. To this end it has it’s own data model description (JSON schema).

The Location provides an address for the location or consumption of a particular resource. To support physical resources which need a physical address, it provides a multi-level hierarchy of address components. At the top are the fairly rigid Institution - Campus - Library, which seeks to provide consistency across various installations of Folio and the different tenants within those. Below that three level hierarchy is the powerful Parking field. The Parking field is an extensible collection of name-value pairs. It can contain both some standardized entries (e.g. LC CallNumbers) as well as institution or library specific address components (e.g. ShelfName, or Department).

To support the needs of electronic resources the Location object provides a Platform field and a URI field

Field		Type	Required	Repeatable	Description
id		string	Y		The internal id of the Location record (UUID)
institution		string			Top level administrative organization (e.g. University)
campus		string			Geographic level (e.g. City)
library		string			Building level (e.g. individual libraries)
parking		object		Y	Extensible collection of name value pairs. Can represent common location properties (e.g. cal numbers) or library specific location details (e.g. shelf number or department)
	name				Name of the parking value (e.g. LCCallNumber or ShelfLocation)
	value				Value tied to the specific parking name
platform		string			Delivery platform (for e-resources)
uri		string			URI to access a resource (for e-resources)

.Location JSON schema.

Coverage

The Coverage object allows the definition of coverage ranges associated with a resource. This is some of what would traditionally be found in a library’’s holding record (holding in the non-Codex sense).

This object allows for the description of multiple ranges which may be specified as dates or in other units such as volumes and issues. Ranges can also be used to represent single dates associated with monographs.

The Coverage object also provides support for embargoes and a free-form coverage statement.

Field		Type	Required	Repeatable	Description
id		string	Y	Y	The internal id of the Coverage record (UUID)
range		object		Y	A set of ranges to describe coverage for the resource Begin and End values specify a range End value is optional (i.e. when specifying date singleton) Range can be specified in time (dates) or volume-issue units
	begin	string			Beginning point in a range
	end	string			Ending point in a range
statement		string			A free form text statement to describe coverage for the resource
embargo		object		Y	A set of ranges to describe embargo periods for a resource
	begin	string			Beginning of embargo
	end	string			End of embargo

Coverage JSON schema.