View Source SmeeFeds.Federation (SmeeFeds v0.3.1)

Federation provides structs that represents federated metadata publishers, and some simple tools to manage the information in them.

Summary

Functions

Returns the default aggregate metadata details for the federation, or nil if none has been defined.

Tags a federation record with one or more tags generated automatically from the federation's other details, returning an updated Federation struct.

Gets the general contact information for the federation as a URL.

Returns the countries associated with the federation as Countries structs.

Returns a description for the federation struct, attempting to use the specified language, but returning the English description if that isn't available. Nil will be returned if no suitable language can be found.

Returns a displayname for the federation struct, attempting to use the specified language, but returning the English displayname or name for the Federation if that isn't available.

Returns an ID for the federation, of the specified type. Defaults to the main (:smee) ID

Returns the default MDQ service for the federation, or nil if none has been defined.

Creates a new Federation struct. The only requirement is a unique ID, passed as the first parameter.

Returns the policy URL for the federation (if known) or nil

Returns a source with the specified source ID, or URL, or nil if one cannot be found.

Returns the sources of the federation struct, as a list of Source structs

Returns the federation with the specified Smee Source structs set as the list of sources, replacing previous sources.

Tags a federation record with one or more tags, replacing existing tags.

Returns the tags of the federation struct, a list of binary strings

Returns the homepage URL for the federation, or nil.

Types

@type t() :: %SmeeFeds.Federation{
  alt_ids: map(),
  autotag: boolean(),
  contact: nil | binary(),
  countries: list(),
  descriptions: map(),
  displaynames: map(),
  id: atom(),
  interfederates: list(),
  logo: nil | binary(),
  name: nil | binary(),
  policy: nil | binary(),
  protocols: list(),
  sources: map(),
  structure: nil | atom(),
  tags: list(),
  type: nil | atom(),
  uri: nil | binary(),
  url: nil | binary()
}

Functions

@spec aggregate(federation :: t()) :: Smee.Source.t() | nil

Returns the default aggregate metadata details for the federation, or nil if none has been defined.

Link to this function

autotag!(federation, options \\ [])

View Source
@spec autotag!(federation :: t(), _options :: keyword()) :: t()

Tags a federation record with one or more tags generated automatically from the federation's other details, returning an updated Federation struct.

Tags will include the federation ID, type, structure, countries, source type, and so on.

Sources in the Federation will also be tagged, and these tags will be inherited by Metadata and Entity structs derived from the Source.

@spec contact(federation :: t()) :: binary()

Gets the general contact information for the federation as a URL.

@spec countries(federation :: t()) :: [binary()]

Returns the countries associated with the federation as Countries structs.

See Countries documentation for more information.

Link to this function

description(federation, lang \\ :en)

View Source
@spec description(federation :: t(), lang :: atom()) :: binary()

Returns a description for the federation struct, attempting to use the specified language, but returning the English description if that isn't available. Nil will be returned if no suitable language can be found.

Link to this function

displayname(federation, lang \\ :en)

View Source
@spec displayname(federation :: t(), lang :: atom()) :: binary()

Returns a displayname for the federation struct, attempting to use the specified language, but returning the English displayname or name for the Federation if that isn't available.

Link to this function

id(federation, id_type \\ :smee)

View Source
@spec id(federation :: t(), id_type :: atom()) :: atom() | binary()

Returns an ID for the federation, of the specified type. Defaults to the main (:smee) ID

  • :smee - returns the main ID
  • :uri - returns the publishing/registration URI
  • :uri_hash - returns sha1 hash of the federation's URI

If other keys are available in the data they can also be specified. The example data has :edugain and :met IDs.

@spec mdq(federation :: t()) :: Smee.Source.t() | nil

Returns the default MDQ service for the federation, or nil if none has been defined.

@spec new(id :: atom() | binary(), options :: keyword()) :: t()

Creates a new Federation struct. The only requirement is a unique ID, passed as the first parameter.

The ID should be a single unique word, as an atom.

Other information can be passed as an option:

default MDQ service.

  • autotag: Boolean, indicates that various explicit tags and inferred tags will be added to sources. Defaults to false.
  • contact: general contact address for the federation, as a URL.
  • countries: A list of 2-letter country codes for countries the federation officially provides services for.
  • descriptions: Map of language codes to descriptions for the federation
  • displaynames: Map of language codes to displaynames for the federation
  • interfederates: List of IDs of other federations this federation pushes data to
  • protocols: List of protocols supported by the federation - defaults to :saml2
  • logo: URL to the logo for the federation
  • name: The full, official, international name of the federation
  • policy: URL for the federation's metadata policy documentation
  • alt_ids: A map of alternative IDs, as used by other services, organisations and lists
  • sources: Map of atom IDs and Smee.Source structs or maps. Use default: for the default aggregate, and mdq: for the main MDQ service.
  • structure: Technical structure of the federation. Values are :mesh, :has, :hybrid. :Defaults to :mesh.
  • tags: List of tags which can be passed down to Sources, Metadata and Entities.
  • type: The federation's type. Possible values are :nren, :research, :inter, :misc, :mil, :com, :local. Defaults to :local
  • uri: The publisher URI of the federation
  • url: The URL of the federation's homepage

Supported options: * :type - The default value is :local.

  • :structure - The default value is :mesh.

  • :alt_ids (map of atom/0 keys and String.t/0 values) - The default value is %{}.

  • :descriptions (map of atom/0 keys and String.t/0 values) - The default value is %{}.

  • :displaynames (map of atom/0 keys and String.t/0 values) - The default value is %{}.

  • :logo - The default value is nil.

  • :autotag (boolean/0) - The default value is false.

  • :interfederates - The default value is [].

  • :tags - The default value is [].

  • :contact (String.t/0)

  • :name (String.t/0)

  • :url (String.t/0)

  • :uri (String.t/0)

  • :countries

  • :protocols

  • :policy (String.t/0)

  • :id

  • :sources - The default value is %{}.

SmeeFeds comes with a list of built-in federations - use SmeeFeds.federations/0 to view them.

@spec policy_url(federation :: t()) :: binary()

Returns the policy URL for the federation (if known) or nil

@spec source(federation :: t(), id :: atom() | binary()) :: Smee.Source.t() | nil

Returns a source with the specified source ID, or URL, or nil if one cannot be found.

IDs will be unique but URLs might not be, so the first matching source will be returned.

@spec sources(federation :: t()) :: [Smee.Source.t()]

Returns the sources of the federation struct, as a list of Source structs

If no sources have been defined it will return an empty list.

Link to this function

sources(federation, sources)

View Source
@spec sources(federation :: t(), sources :: Smee.Source.t() | [Smee.Source.t()]) ::
  t()

Returns the federation with the specified Smee Source structs set as the list of sources, replacing previous sources.

Only proper Source structs will be added, everything else will be silently ignored.

Sources with IDs will be added with those IDs. Sources without IDs will be added with IDs like "source0", "source1", etc. Sources with conflicting IDs will be overwritten by the last one in the list.

@spec tag(federation :: t(), tags :: list() | nil | binary()) :: t()

Tags a federation record with one or more tags, replacing existing tags.

Tags are arbitrary strings.

@spec tags(federation :: t()) :: [binary()]

Returns the tags of the federation struct, a list of binary strings

Tags are arbitrary strings.

@spec url(federation :: t()) :: binary()

Returns the homepage URL for the federation, or nil.