@spec base(String.t() | nil) :: String.t() | nil

Returns the URI or reference without its fragment.

Removes the first literal # and everything after it, without decoding or normalizing the URI. Fragment-only references return ""; a missing URI remains nil, so absence is not confused with an explicitly empty reference. Callers that require an empty resource key can normalize with base(uri) || "".

Examples

iex> JSONSchex.URIUtil.base("https://example.com/schema#meta")
"https://example.com/schema"

iex> JSONSchex.URIUtil.base("schema.json?version=1#/definitions/value")
"schema.json?version=1"

iex> JSONSchex.URIUtil.base("urn:example:schema")
"urn:example:schema"

iex> JSONSchex.URIUtil.base("#/definitions/value")
""

iex> JSONSchex.URIUtil.base("")
""

iex> JSONSchex.URIUtil.base(nil)
nil

@spec fragment(String.t()) :: String.t() | nil

Returns only the fragment portion of a URI or reference, without the leading #.

Examples

iex> JSONSchex.URIUtil.fragment("https://example.com/schema#meta")
"meta"

iex> JSONSchex.URIUtil.fragment("#/$defs/foo")
"/$defs/foo"

iex> JSONSchex.URIUtil.fragment("https://example.com/schema")
nil

@spec join_fragment(String.t(), String.t() | nil) :: String.t()

Joins a fragment-free base URI and a fragment into a URI reference.

The fragment should be provided without the leading #. Passing nil returns the base unchanged; an empty fragment appends #. No URI parsing, encoding, normalization, or replacement of an existing fragment is performed.

Examples

iex> JSONSchex.URIUtil.join_fragment("https://example.com/schema", "meta")
"https://example.com/schema#meta"

iex> JSONSchex.URIUtil.join_fragment("https://example.com/schema", "/$defs/foo")
"https://example.com/schema#/$defs/foo"

iex> JSONSchex.URIUtil.join_fragment("https://example.com/schema", nil)
"https://example.com/schema"

iex> JSONSchex.URIUtil.join_fragment("https://example.com/schema", "")
"https://example.com/schema#"

iex> JSONSchex.URIUtil.join_fragment("", "/$defs/foo")
"#/$defs/foo"

@spec local_ref(String.t() | nil) :: String.t()

Converts a fragment into a local reference string.

The fragment should be provided without the leading #. Passing nil returns "#".

Examples

iex> JSONSchex.URIUtil.local_ref("meta")
"#meta"

iex> JSONSchex.URIUtil.local_ref("/$defs/foo")
"#/$defs/foo"

iex> JSONSchex.URIUtil.local_ref(nil)
"#"

@spec remote_ref?(String.t()) :: boolean()

Checks if a reference string represents a remote URI (http or https).

Examples

iex> JSONSchex.URIUtil.remote_ref?("https://example.com/schema.json")
true

iex> JSONSchex.URIUtil.remote_ref?("http://example.com/schema.json")
true

iex> JSONSchex.URIUtil.remote_ref?("#/definitions/user")
false

iex> JSONSchex.URIUtil.remote_ref?("urn:uuid:12345")
false

@spec resolve(String.t() | nil, String.t() | nil) :: String.t() | nil

Resolves a relative URI against a base URI. Safely handles cases where URIs are invalid or nil.

If merging fails (e.g. invalid URI format), it falls back to returning the child URI (or the base if child is nil).

Examples

iex> JSONSchex.URIUtil.resolve("https://example.com/schema.json", "user.json")
"https://example.com/user.json"

iex> JSONSchex.URIUtil.resolve("https://example.com/schemas/", "#/definitions/user")
"https://example.com/schemas/#/definitions/user"

iex> JSONSchex.URIUtil.resolve(nil, "https://example.com/schema.json")
"https://example.com/schema.json"

@spec split_fragment(String.t()) :: {String.t(), String.t() | nil}

Splits a URI or reference into {base, fragment}.

Only the first literal # separates the base from the fragment. The fragment is returned without that leading #. If no fragment is present, the second element is nil. An empty fragment ("#") is also normalized to nil.

Examples

iex> JSONSchex.URIUtil.split_fragment("https://example.com/schema")
{"https://example.com/schema", nil}

iex> JSONSchex.URIUtil.split_fragment("https://example.com/schema#meta")
{"https://example.com/schema", "meta"}

iex> JSONSchex.URIUtil.split_fragment("#/$defs/foo")
{"", "/$defs/foo"}

iex> JSONSchex.URIUtil.split_fragment("https://example.com/schema#")
{"https://example.com/schema", nil}

@spec with_fragment(String.t(), String.t() | nil) :: String.t()

Deprecated alias for join_fragment/2.