JSV.Resolver behaviour (jsv v0.4.0)
View SourceResolves 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
@type resolvable() :: JSV.Key.ns() | JSV.Key.pointer() | JSV.Ref.t()
@opaque t()
Callbacks
@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
@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.
@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.
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.
@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.