JSV.Resolver behaviour (jsv v0.4.0)

View Source

Resolves remote resources when building a JSON schema.

A resolver implementation is needed for JSV.build/2.

There are no specific rules on how to build a proper resolver. Anything is valid as long as it returns a JSON schema (or an error) for a given URI.

Custom resolvers are most often used for:

  • Ability to resolve URLs such as my-company://some-id/ where the implementation knows a directory to retrieve that path from.
  • Ability to resolve https:// URLs with custom network setups involving authentication, proxies, etc.
  • Returning hardcoded schemas directly from the codebase, or files from the codebase.
  • Returning a different schema depending on the environment, whether this is a good idea or not.

Custom resolvers should delegate to the JSV.Resolver.Internal resolver for easy support of the internal resolution features.

Internal resolution

The JSV library supports exporting schemas from Elixir modules. A valid module for this feature is any module that exports a schema/0 function:

defmodule MyApp.Schemas.MySchema do
  def schema do
    %{"type" => "integer"}
  end
end

URI references to such modules are defined by the jsv scheme and a module:<module to string> path:

%{
  "$ref" => "jsv:module:Elixir.MyApp.Schemas.MySchema"
}

The internal resolver will automatically call the schema/0 function from modules referenced this way in order to resolve the referenced URI.

Summary

Callbacks

Receives an URI and the options passed in the resolver tuple to JSV.build/2 and returns a result tuple for a raw JSON schema, that is a map with binary keys or a boolean.

Functions

Returns the raw schema identified by the given namespace if was previously resolved as a meta-schema.

Returns the raw schema identified by the given key if was previously resolved.

Returns a new resolver, with the given module for behaviour implementation, and a default meta-schema URL to use with schemas that do not declare a $schema property.

Returns the resolver with the remote resolvable resource fetched in the internal cache of the resolver.

Adds the given raw schema as a pre-resolved schema, using the :root namespace if the schema does not contain a $id property.

Types

resolvable()

@type resolvable() :: JSV.Key.ns() | JSV.Key.pointer() | JSV.Ref.t()

t()

@opaque t()

Callbacks

resolve(uri, opts)

@callback resolve(uri :: String.t(), opts :: term()) ::
  {:ok, JSV.raw_schema()} | {:error, term()}

Receives an URI and the options passed in the resolver tuple to JSV.build/2 and returns a result tuple for a raw JSON schema, that is a map with binary keys or a boolean.

Functions

fetch_meta(rsv, meta)

@spec fetch_meta(t(), binary()) :: {:ok, JSV.Resolver.Resolved.t()} | {:error, term()}

Returns the raw schema identified by the given namespace if was previously resolved as a meta-schema.

fetch_resolved(rsv, pointer)

@spec fetch_resolved(t(), resolvable() | {:meta, resolvable()}) ::
  {:ok, JSV.Resolver.Resolved.t() | {:alias_of, JSV.Key.t()}} | {:error, term()}

Returns the raw schema identified by the given key if was previously resolved.

new(module, default_meta)

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

Returns a new resolver, with the given module for behaviour implementation, and a default meta-schema URL to use with schemas that do not declare a $schema property.

resolve(rsv, resolvable)

@spec resolve(t(), resolvable() | {:prefetched, term(), term()}) ::
  {:ok, t()} | {:error, term()}

Returns the resolver with the remote resolvable resource fetched in the internal cache of the resolver.

resolve_root(rsv, raw_schema)

@spec resolve_root(t(), JSV.raw_schema()) ::
  {:ok, :root | binary(), t()} | {:error, term()}

Adds the given raw schema as a pre-resolved schema, using the :root namespace if the schema does not contain a $id property.