DSpace.API.Model.MetadataValue (dspace_ex v0.2.1)

Represents a single metadata value.

A metadata value in DSpace can have additional properties like language, an authority key, and security level alongside its main text content. Metadata values might also be grouped by positional correlation with other values.

Example

%{
  "dc.publisher" => [
    %DSpace.API.Model.MetadataValue{
      value: "Telefonaktiebolaget LM Ericsson",
      language: "se",
      authority: "550e8400-e29b-41d4-a716-446655440000",
      confidence: :accepted,
      place: 0,
      security_level: :public
    }
  ]
}

Summary

Types

confidence_score()

DSpace authority matching confidence values.

security_level()

Security levels for metadata values.

t()

A single DSpace metadata value.

Functions

new(value, opts \\ [])

Builds a metadata value.

placeholder(placeholder \\ "#PLACEHOLDER_PARENT_METADATA_VALUE#")

Builds a placeholder metadata value for positionally-correlated groups.

placeholder?(module, placeholder \\ "#PLACEHOLDER_PARENT_METADATA_VALUE#")

Checks if the metadata value is a placeholder.

relation(display_value, authority, opts \\ [])

Builds a relation (authority-linked) metadata value.

Types

confidence_score()

(since 0.2.0)

@type confidence_score() ::
  :accepted
  | :uncertain
  | :ambiguous
  | :not_found
  | :failed
  | :rejected
  | :no_value
  | :unset

DSpace authority matching confidence values.

:accepted - Confirmed accurate by a user or policy
:uncertain - Valid but unconfirmed, used for programmatic relation links
:ambiguous - Multiple equally valid matches
:not_found - No matching authority values
:failed - Internal authority failure
:rejected - Authority recommends rejection
:no_value - No confidence value available
:unset - Not yet evaluated (default)

security_level()

(since 0.2.0)

@type security_level() :: :public | :trusted | :admin_owner

Security levels for metadata values.

Note that these levels are a configurable property. An instance might define additional/ different security levels. The structure described here is the default. Metadata security levels are originally a feature of the CRIS fork, and available on vanilla DSpace >= 10.0

:public - Available to all users (including anonymous)
:trusted - Available to authenticated users in the "Trusted" group
:admin_owner - Available only to administrators and entity owner

t()

(since 0.2.0)

@type t() :: %DSpace.API.Model.MetadataValue{
  authority: binary() | nil,
  confidence: confidence_score() | nil,
  language: binary() | nil,
  place: non_neg_integer() | nil,
  security_level: security_level() | nil,
  value: binary() | nil
}

A single DSpace metadata value.

Fields

value - The actual content (required)
language - Language code (optional)
authority - Authority key for controlled values; DSpace Object UUID or controlled vocabulary key (optional)
confidence - Authority matching confidence
place - Position in multi-value fields (0-based)
security_level - Access restriction level

Functions

new(value, opts \\ [])

(since 0.2.0)

@spec new(binary(), keyword()) :: t()

Builds a metadata value.

Examples

iex> DSpace.API.Model.MetadataValue.new("John")
%DSpace.API.Model.MetadataValue{
  value: "John",
  confidence: :unset,
  language: nil,
  authority: nil,
  place: nil,
  security_level: nil
}

iex> DSpace.API.Model.MetadataValue.new("Test", language: "en", confidence: :accepted)
%DSpace.API.Model.MetadataValue{
  value: "Test",
  confidence: :accepted,
  language: "en",
  authority: nil,
  place: nil,
  security_level: nil
}

iex> DSpace.API.Model.MetadataValue.new("Test", security_level: :public)
%DSpace.API.Model.MetadataValue{
  value: "Test",
  confidence: :unset,
  language: nil,
  authority: nil,
  place: nil,
  security_level: :public
}

placeholder(placeholder \\ "#PLACEHOLDER_PARENT_METADATA_VALUE#")

(since 0.2.0)

@spec placeholder(binary()) :: t()

Builds a placeholder metadata value for positionally-correlated groups.

Used when a position in a group has no value but alignment must be preserved.

The placeholder's text value is configurable for DSpace instances, per default it's #PLACEHOLDER_PARENT_METADATA_VALUE#. Pass a custom value to this function if the instance you are working with has a different placeholder value configured.

Examples

iex> DSpace.API.Model.MetadataValue.placeholder()
%DSpace.API.Model.MetadataValue{
  value: "#PLACEHOLDER_PARENT_METADATA_VALUE#",
  confidence: :unset,
  language: nil,
  authority: nil,
  place: nil,
  security_level: nil
}

iex> DSpace.API.Model.MetadataValue.placeholder("MYPLACEHOLDER")
%DSpace.API.Model.MetadataValue{
  value: "MYPLACEHOLDER",
  confidence: :unset,
  language: nil,
  authority: nil,
  place: nil,
  security_level: nil
}

placeholder?(module, placeholder \\ "#PLACEHOLDER_PARENT_METADATA_VALUE#")

(since 0.2.0)

@spec placeholder?(t(), binary()) :: boolean()

Checks if the metadata value is a placeholder.

Placeholders are used in positionally-correlated metadata groups where a position has no value.

Examples

iex> placeholder = DSpace.API.Model.MetadataValue.placeholder()
iex> DSpace.API.Model.MetadataValue.placeholder?(placeholder)
true

iex> custom_placeholder = DSpace.API.Model.MetadataValue.placeholder("MYPLACEHOLDER")
iex> DSpace.API.Model.MetadataValue.placeholder?(custom_placeholder, "MYPLACEHOLDER")
true

relation(display_value, authority, opts \\ [])

(since 0.2.0)

@spec relation(binary(), binary(), keyword()) :: t()

Builds a relation (authority-linked) metadata value.

Examples

iex> DSpace.API.Model.MetadataValue.relation("Department of Physics", "550e8400-e29b-41d4-a716-446655440000")
%DSpace.API.Model.MetadataValue{
  value: "Department of Physics",
  authority: "550e8400-e29b-41d4-a716-446655440000",
  confidence: :uncertain,
  language: nil,
  place: nil,
  security_level: nil
}

iex> DSpace.API.Model.MetadataValue.relation("Department", "uuid", confidence: :accepted)
%DSpace.API.Model.MetadataValue{
  value: "Department",
  authority: "uuid",
  confidence: :accepted,
  language: nil,
  place: nil,
  security_level: nil
}