pocket_archive/doc/submission.md

Submission process

The following are basic guidelines to build a submission package:

• Resources are arranged in files and folders on a local filesystem that Pocket Archive can access.
• File and folder arrangement is important. A folder represents a descriptive resource, and can have metadata attached to it. A file of folder under a parent folder is automatically added as a child of the parent resource. This relationship is intended to present the parent as a container of other sub-resources (descriptive and/or opaque). With this method, hierarchies of any complexity can be built.
• File and folder order in the submission folder is not important. No need to rename files and folders to force a specific ordering. This is specified via laundry list instead. See below.
• The laundry list file is placed under the submission package folder and must be named pkar_submission.csv.

A laundry list is thus formatted:

• The first row is reserved for the headers, which indicate the field names.
• Each subsequent row represents a resource (except in a multi-value case, described below). The pas:sourcePath and pas:contentType fields are mandatory for each resource. All other fields are optional for the submission, however, some type definitions may have constraints in this regard.
• All field names, except for id, have a namespace prefix among the ones defined in the configuration. See dedicated section for details about namespaces.
• Fields with a special meaning:
  • id: optional and single-valued. If provided, it becomes the primary identifier for the resource, which is used anywhere information about the resource is retrieved. The depositor is responmsible for ensuring that the provided ID is unique across the system. If left blank, the system generates an identifier that is guaranteed to be unique.
  • pas:sourcePath: mandatory and single-valued. It refers to the file or folder path relative to the package.
  • pas:contentType: mandatory and single-valued. It defines the content type assigned to the resource. For files, it should be pas:File or a sub-type thereof. For folders it must not be a pas:File or sub-type.
• To provide multiple values for one or more fields, additional values are added to rows below the previous. For these additional rows, the sourcePath field must not be filled, and additional values for single-valued fields are ignored.
• The ordering of the rows determines the ordering of the resources in their container. The system automatically assigns an order to the resources, using their source path and their position in the laundry list. Resources at the top are not assigned an order, as they are considered self-standing. If an order is needed for those, the pas:next field can be set to the desired resource (see point below about relationships), or they can be put in an enclosing folder that acts as a collection.
• Relationships can be established between resources. These are stored as persistent links and appear as hyperlinks in the discovery interface. A relationship can only be set for a field that is configured as "resource" type. To set a relationship with a resource in the same laundry list that doesn't have an explicit ID set, insert the source path of the resource. For a resource that has already an ID, either by being assigned one manually or by being already deposited, insert the full ID including the par: namespace (e.g. for ID 12345, insert par:12345).

Update

A submission is also used to update existing resources. Each resource update is a full replacement of all the resource's metadata, so a submission must include a full representation of each of the resources updated.

To facilitate this task while avoiding the need to hold on to all of the archive's laundry lists, Pocket Archive can generate a laundry list for one or more selected resources. This list, which represents the current state of the resources requested, can be edited and submitted for an update.