Boxic.DMN (boxic_dmn v0.2.0)

Loads, validates, and evaluates DMN models.

Use load_file/1 when the input is a path and load_xml/1 when the input is XML. load/1 remains available for backwards compatibility and dispatches XML-looking input to load_xml/1; all other input is treated as a path.

Summary

Types

evaluation_error()

An error produced while resolving or evaluating a decision.

load_error()

An error returned while reading or decoding a DMN document.

validation_error()

A structural problem found while validating a normalized model.

Functions

encode_xml(model, opts \\ [])

Encodes a normalized DMN model as deterministic DMN XML.

evaluate(model, decision_name, context \\ %{})

Evaluates a named decision using the supplied input context.

evaluate(model, decision_name, context, opts)

Evaluates a named decision with evaluator options.

evaluate_service(model, service_name, arguments)

Evaluates a named decision service.

load(path_or_xml)

Loads a DMN document from either an XML string or a file path.

load_file(path)

Loads a DMN document and its sibling imports from path.

load_xml(xml)

Loads a DMN document from an XML string.

validate(model)

Validates a normalized DMN model.

validate_serializable(model, opts \\ [])

Checks whether a normalized model can be encoded without data loss.

Types

evaluation_error()

@type evaluation_error() ::
  Boxic.FEEL.Error.t()
  | {atom(), term()}
  | {atom(), term(), term()}
  | {atom(), term(), term(), term()}

An error produced while resolving or evaluating a decision.

load_error()

@type load_error() ::
  {:file_error, Path.t(), File.posix()}
  | :invalid_xml
  | :trailing_xml_content
  | :invalid_definitions_document

An error returned while reading or decoding a DMN document.

validation_error()

@type validation_error() ::
  {atom(), term()} | {atom(), term(), term()} | {atom(), term(), term(), term()}

A structural problem found while validating a normalized model.

Functions

encode_xml(model, opts \\ [])

@spec encode_xml(
  Boxic.DMN.Model.t(),
  keyword()
) :: {:ok, String.t()} | {:error, [Boxic.DMN.SerializationError.t()]}

Encodes a normalized DMN model as deterministic DMN XML.

The model must originate from the pinned DMN profile and have complete serialization fidelity. Supported options are:

:format — :pretty (default) or :compact;
:xml_declaration — whether to emit the UTF-8 XML declaration, defaulting to true.

Pretty output uses two-space indentation, LF line endings, and one final newline. Compact output contains no presentation whitespace. FEEL text is escaped but otherwise preserved.

evaluate(model, decision_name, context \\ %{})

@spec evaluate(Boxic.DMN.Model.t(), String.t(), map()) ::
  {:ok, term()} | {:error, evaluation_error()}

Evaluates a named decision using the supplied input context.

Boxic.DMN.evaluate(model, "Price", %{"quantity" => Decimal.new("2")})

evaluate(model, decision_name, context, opts)

@spec evaluate(Boxic.DMN.Model.t(), String.t(), map(), keyword()) ::
  {:ok, term()} | {:error, evaluation_error()}

Evaluates a named decision with evaluator options.

Boxic.DMN.evaluate(model, "Price", inputs,
  external_functions: MyApp.DecisionFunctions
)

evaluate_service(model, service_name, arguments)

@spec evaluate_service(Boxic.DMN.Model.t(), String.t(), map() | list()) ::
  {:ok, term()} | {:error, evaluation_error()}

Evaluates a named decision service.

Boxic.DMN.evaluate_service(model, "Pricing Service", %{"order" => order})

load(path_or_xml)

@spec load(String.t()) :: {:ok, Boxic.DMN.Model.t()} | {:error, load_error()}

Loads a DMN document from either an XML string or a file path.

New code should prefer load_xml/1 or load_file/1, which avoid input ambiguity.

Boxic.DMN.load("<definitions id="example" namespace="urn:example"/>")

load_file(path)

@spec load_file(Path.t()) :: {:ok, Boxic.DMN.Model.t()} | {:error, load_error()}

Loads a DMN document and its sibling imports from path.

Boxic.DMN.load_file("priv/decisions/pricing.dmn")

load_xml(xml)

@spec load_xml(String.t()) :: {:ok, Boxic.DMN.Model.t()} | {:error, load_error()}

Loads a DMN document from an XML string.

Boxic.DMN.load_xml("<definitions id="example" namespace="urn:example"/>")

validate(model)

@spec validate(Boxic.DMN.Model.t()) :: :ok | {:error, [validation_error()]}

Validates a normalized DMN model.

with {:ok, model} <- Boxic.DMN.load_xml(xml) do
  Boxic.DMN.validate(model)
end

validate_serializable(model, opts \\ [])

@spec validate_serializable(
  Boxic.DMN.Model.t(),
  keyword()
) :: :ok | {:error, [Boxic.DMN.SerializationError.t()]}

Checks whether a normalized model can be encoded without data loss.

This runs the same model, option, version, fidelity, identifier, reference, and unsupported-expression checks as encode_xml/2 without producing XML.