DSpace.API.Metadata.Value (dspace_ex v0.1.0-alpha2)

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.Metadata.Value{
      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()

DSpace-CRIS security levels for metadata values.

t()

A single DSpace metadata value.

Functions

from_map(map)

Creates a Value from a string-keyed DSpace API JSON map.

new(value, opts \\ [])

Builds a plain metadata value with default confidence :unset.

no_value_placeholder()

placeholder()

Builds a placeholder Value for positionally-correlated groups.

placeholder?(value)

Returns true if the value is a placeholder.

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

Builds a relation (authority-linked) metadata value with confidence: :uncertain by default.

to_map(value)

Converts a Value to a string-keyed map with DSpace API JSON field names.

Types

confidence_score()

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

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

DSpace-CRIS 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.

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

@type t() :: %DSpace.API.Metadata.Value{
  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)

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

Creates a Value from a string-keyed DSpace API JSON map.

Missing keys default to nil. Ignores unknown keys.

Examples

iex> map = %{
...>   "value" => "test",
...>   "language" => "en",
...>   "confidence" => 600,
...>   "securityLevel" => 1
...> }
iex> DSpace.API.Metadata.Value.from_map(map)
%DSpace.API.Metadata.Value{
  value: "test",
  language: "en",
  authority: nil,
  confidence: :accepted,
  place: nil,
  security_level: :trusted
}

new(value, opts \\ [])

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

Builds a plain metadata value with default confidence :unset.

Examples

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

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

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

no_value_placeholder()

@spec no_value_placeholder() :: binary()

placeholder()

@spec placeholder() :: t()

Builds a placeholder Value for positionally-correlated groups.

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

Examples

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

placeholder?(value)

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

Returns true if the value is a placeholder.

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

Examples

iex> placeholder = DSpace.API.Metadata.Value.placeholder()
iex> DSpace.API.Metadata.Value.placeholder?(placeholder)
true

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

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

Builds a relation (authority-linked) metadata value with confidence: :uncertain by default.

Examples

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

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

to_map(value)

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

Converts a Value to a string-keyed map with DSpace API JSON field names.

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).

Examples

iex> value = %DSpace.API.Metadata.Value{
...>   value: "test",
...>   language: "en",
...>   authority: "uuid",
...>   confidence: :accepted,
...>   place: 0,
...>   security_level: :public
...> }
iex> DSpace.API.Metadata.Value.to_map(value)
%{
  "value" => "test",
  "language" => "en",
  "authority" => "uuid",
  "confidence" => 600,
  "place" => 0,
  "securityLevel" => 0
}

iex> value = %DSpace.API.Metadata.Value{value: "test"}
iex> DSpace.API.Metadata.Value.to_map(value)
%{"authority" => nil, "confidence" => nil, "language" => nil, "place" => nil, "value" => "test"}