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

Represents a single DSpace metadata value.

A metadata value in DSpace can have additional properties like language, an authority key, and security level alongside its main text content.

This struct is not used internally by dspace_ex, API responses are returned as plain maps and deserialisation is left to the caller. You can use the module for building, converting and querying metadata values in your application if you want a typed representation when constructing or inspecting metadata 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

from_map(map)

Creates a value structure from a wire format map.

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.

to_map(struct)

Converts a value structure to a wire format map.

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()
}

A single DSpace metadata value.

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

from_map(map)

(since 0.2.0)

@spec from_map(map()) :: t()

Creates a value structure from a wire format map.

Missing keys default to nil.

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
}

to_map(struct)

(since 0.2.0)

@spec to_map(struct()) :: %{required(binary()) => term()}

@spec to_map(t()) :: map()

Converts a value structure to a wire format map.

All fields are always emitted. The only exception is "securityLevel": it is omitted when nil, because DSpace-CRIS treats its absence differently from an explicit null (absence means "no access restriction set"; null is not a valid wire value for that field).