BagItProfile

BagItProfile

BagItProfile describes what constitutes a valid bag. These profiles are based on the BagIt profiles described in https://github.com/bagit-profiles/bagit-profiles, with some changes and additions.

Constructor

new BagItProfile(opts)

Parameters:
Name Type Description
opts object

Object containing properties to set.

Properties
Name Type Description
id string

A UUID in hex-string format. This is the object's unique identifier.
userCanDelete boolean

Indicates whether user is allowed to delete this record.
name string

The name this profile.
description string

A helpful description of the profile for people who will be using it.
Default Value:
  • 'New custom BagIt profile'
Source:
See:

Members

acceptBagItVersion :Array.<string>

A list of BagIt versions that are valid for bags that conform to this profile. For example, '0.97'.

Default Value:
  • ['0.97']
Source:

acceptSerialization :Array.<string>

A list of BagIt sserialization formats that are valid for bags that conform to this profile. These may include 'application/tar', 'application/zip', 'application/x-rar-compressed', etc.

Default Value:
  • ['tar']
Source:

allowFetchTxt :boolean

This describes whether bags conforming to this profile may have a fetch.txt file.

Default Value:
  • false
Source:

bagItProfileInfo :BagItProfileInfo

This contains metadata about the BagIt profile itself, such as who publishes and maintains it.

Source:

baseProfileId :string

baseProfileId allows us to track whether this profile is based on a built-in. If so, we don't allow the user to modify certain elements of the profile. This will be blank for many profiles.

Default Value:
  • null
Source:

description :string

The description of this profile should be meaningful to the user.

Source:

errors :Object.<string, string>

Contains information describing validation errors. Key is the name of the invalid field. Value is a description of why the field is not valid.

Source:

isBuiltIn :boolean

Describes whether this profile is built into the application. Builtin profiles cannot be deleted by users.

Default Value:
  • false
Source:

manifestsAllowed :Array.<string>

A list of supported algorithms for payload manifests.

Default Value:
Source:

manifestsRequired :Array.<string>

A list of algorithms of required manifests. For example, 'sha256' indicates that bags conforming to this profile must have a manifest-sha256.txt file.

Default Value:
  • ['sha256']
Source:

name :string

Name is the name of this profile. Names should be unique, to prevent confusion.

Source:

serialization :string

Describes whether bags conforming to this profile may or may not be serialized. Allowed values are 'required', 'optional', and 'forbidden'.

Default Value:
  • 'optional'
Source:

tagFilesAllowed :Array.<string>

List of allowed tag files. This is a list of file names, and can use glob matching patterns, such as ['custom-tags/', 'my-tags/.txt', 'other-tags/info.txt', 'credits.txt']. If this list is empty or not present, it is assumed to be ['*'], per the BagItProfile spec at https://github.com/bagit-profiles/bagit-profiles

Default Value:
  • ['*']
Source:

tagManifestsAllowed :Array.<string>

A list of supported algorithms for tag manifests.

Default Value:
Source:

tagManifestsRequired :Array.<string>

A list of algorithms of required tag manifests. For example, 'sha256' indicates that bags conforming to this profile must have a tagmanifest-sha256.txt file. Leave this empty if no tag manifests are required.

Default Value:
  • []
Source:

tags :Array.<TagDefinition>

A list of tags that you expect to be present or expect to parse when creating or validating bags that conform to this profile.

Note that this property was called requiredTags in prior versions of DART, and in the BagItProfile JSON from those versions.

Source:

tarDirMustMatchName :boolean

Describes whether a tarred bag MUST untar to a directory whose name matches the tar file name.

E.g. Must bag "photos123.tar" untar to a directory called "photos123". The APTrust and DPN specs, as well as some others, require this, though the official BagIt spec does not.

Default Value:
  • false
Source:

Methods

(static) find(id) → {BagItProfile}

find finds the BagItProfile with the specified id in the datastore and returns it. Returns null if the object is not in the datastore.

This overrides the find() method of PersistentObject to return a correctly constructed BagItProfile object.

Parameters:
Name Type Description
id string

The id (UUID) of the BagItProfile you want to find.
Source:

(static) fromJson(jsonString) → {BagItProfile}

This converts the stored representation, which is basically a JSON hash, to a full-fledged BagItProfile object.

See also BagItProfile.load

Parameters:
Name Type Description
jsonString string

String of JSON to covert to BagItProfile.
Source:
Throws:
  • Throws SyntaxError if jsonString cannot be parsed.
Type
SyntaxError

(static) inflateFrom(otherProfile) → {BagItProfile}

This creates a new BagItProfile or a vanilla data object that contains the attributes of a BagItProfile. This is used by the find() method to inflate a JSON hash retrieved from the DB into a full-fledged BagItProfile object, and by the BagItProfileController when creating a new BagItProfile based on an existing BagItProfile.

If you intend to clone an existing profile to create a new one, be sure to change the profile's id after cloning it. Otherwise, when you save the new (cloned) profile, it will overwrite the old one in the DB.

Parameters:
Name Type Description
otherProfile BagItProfile | object

The BagItProfile you want to copy, or a vanilla object that contains the same properties as a BagItProfile (such as BagItProfile JSON record retrieved from the DART database).
Source:

(static) load(pathToJsonFile) → {BagItProfile}

This loads a BagItProfile from a JSON file and returns the BagItProfile object. After you've loaded the profile, you can call the validate() method to make sure it's valid.

This is a synchronous operation, and will throw errors if file does not exist, is not readable, JSON is invalid, etc.

See also BagItProfile.fromJson

Parameters:
Name Type Description
pathToJsonFile string

The path to the JSON file that contains the profile you want to load.
Source:

(static) nameLooksLegal(name) → {boolean}

This returns true if the bag name contains no illegal characters. Illegal characters include <, >, :, ", /, , ?, *, space, tab, carriage return and newline.

Parameters:
Name Type Description
name string

The bag name you want to validate.
Source:

(static) suggestGenericBagName() → {string}

This returns a generic unique bag name suggestion.

Source:

bagDescription() → {string}

Returns the best guess at bag description by checking tags called 'Internal-Sender-Description' and 'Description' in the tag files.

Source:

bagInternalIdentifier() → {string}

Returns the bag's Internal-Sender-Identifier as specified in the tag files, or an empty string if there is none. It's common for this tag to appear in a tag file with no value, which also leads to an empty string return value.

Also note that this returns the value of the first Internal-Sender-Identfier tag in the bag-info.txt file.

Source:

bagTitle() → {string}

Returns the best guess at bag title by checking tags called 'Title' or that include 'Title' in the tag files.

Source:

chooseManifestAlgorithms(whichType)

Chooses one or more manifest/tag manifest algorithms using the following rules:

  • If the manifest of the other type (i.e. payload vs. tag manifest) is specified, choose the same algorithm that the other manifest is already using. (Per the spec at https://tools.ietf.org/html/rfc8493#section-2.2.1 - tag manifest algorithm should match payload manifest algorithm.)
  • If the required list is non-empty, use the algorithms specified there.
  • If required is empty and allowed is empty, use sha-512 (per LOC recommendation)
  • If required is empty and allowed is not, choose one of the following from allowed, in this order: "sha512", "sha256", "md5", first item in allowed list.
Parameters:
Name Type Description
whichType string

Should be either 'manifest' or 'tagmanifest'. This determines whether the function looks at manifestsAllowed/manifestsRequired or tagManifestsAllowed/tagManifestsRequired.
Source:

copyDefaultTagValuesFrom(otherProfile)

Copy default tag values from other profile to this profile.

If multiple tags with the same name appear in the same tag file, this copies only the first value. While the BagIt spec permits multiple instances of a tag within a file, we're assuming (naively?) that a BagItProfile will specify only one default value for a tag in a given file.

This method is generally used for cloning BagItProfiles. If you want to copy userValues, for instance, when you're creating a bag, see mergeTagValues.

Parameters:
Name Type Description
otherProfile BagItProfile

The BagItProfile whose TagDefinition default values you want to copy.
Source:

findExactOrPartial() → {string}

Returns the value of the first tag whose name matches exactTagName, or if there are none, the value of the the first tag whose name contains partialTagName. Names are case insensitive.

Source:

findMatchingTags(property, value) → {Array.<TagDefinition>}

findMatchingTags returns an array of TagDefinition objects matching the specified criteria.

Parameters:
Name Type Description
property string

The name of the TagDefinition property to match. For example, 'tagName' or 'defaultValue'.
value string

The value of the property to match.
Source:
See:
  • also findMatchingTag

firstMatchingTag(property, value) → {TagDefinition}

findMatchingTag returns the first TagDefinition object that matches the specified criteria.

Parameters:
Name Type Description
property string

The name of the TagDefinition property to match. For example, 'tagName' or 'defaultValue'.
value string

The value of the property to match.
Source:
See:
  • also findMatchingTags

getTagFileContents(name) → {string}

getTagFileContents returns a string that you can write to the tag file when creating a bag. Use requiredTagFileNames to get all tag file names.

Parameters:
Name Type Description
name string

The name of the tag file (relative path within the bag)
Source:
Example
var contents = profile.getTagFileContentsByName(filename)
// returns
// Tag-Name: Value
// Other-Tag: Other value

getTagsFromFile(filename, tagname) → {Array.<TagDefinition>}

getTagsFromFile returns all tags with the specified tagname from the specified file. This usually returns zero or one results, but because the BagIt spec says a tag can appear multiple times in a file, this may return a list.

Parameters:
Name Type Description
filename string

The name of the tagfile.
tagname string

The name of the tag.
Source:
See:
  • also findMatchingTags

hasTagFile(filename) → {boolean}

This returns true if the tags list includes a tagfile with the specified filename.

Parameters:
Name Type Description
filename string

The name of the tagfile.
Source:

isCustomTagFile(filename) → {boolean}

Returns true if filename is a custom file added for a specific job (i.e. is not part of the core profile). All tags in a custom tag file have isUserAddedTag = true.

Parameters:
Name Type Description
filename string

The name of the tag file to check.
Source:

isValidBagName(name) → {boolean}

This returns true if the name is legal for this profile.

Parameters:
Name Type Description
name string

The bag name you want to validate.
Source:

mergeTagValues(tags)

Copy values into the userValue field of this profile's tags. Use this when you're creating a bag and you want to write actual values into the bag's tag files (as opposed to when you are creating a reusable BagItProfile).

If multiple tags with the same name appear in the same tag file, this copies only the first value. If a tag in the tags param does not exist in the profile, it will be added for one-time use. (That is, it will be added to the profile for the scope of one bagging or validation operation, but will not be saved as part of the reusable BagItProfile.)

If you want to copy default values when cloning an existing BagItProfile, see copyDefaultValuesFrom.

Parameters:
Name Type Description
tags Array.<TagDefinition>

An array of tags whose userValues you want to copy into this profile.
Source:

mustBeTarred() → {boolean}

Returns true if this profile says the bag must be tarred.

Source:

preferredSerialization()

This returns the file extension of the first allowed serialization in the {@see acceptSerialization} list, if it is defined and serialization is not forbidden. Otherwise, this returns an empty string.

@ returns {string}

Source:

suggestBagName() → {string}

This returns a suggested unique bag name that is valid for the current profile.

TODO: This belongs in a profile or in a vendor-specific module.

Source:

tagFileNames() → {Array.<string>}

Returns the names of all tag files, in alpha order.

Source:

tagsGroupedByFile() → {Object.<string, Array.<TagDefinition>>}

Returns a hash of required tags, with filename as the key. Value is a list of required tags, in alpha order by name.

Source:

validate() → {boolean}

validate returns true or false, indicating whether this object contains complete and valid data. If it returns false, check the errors property for specific errors.

Source: