A2UICore.Catalog.Refs (A2UICore v0.1.1)

$ref handling for catalog documents.

A catalog document references three kinds of target:

the protocol's common types, as common_types.json#/$defs/X (or a path ending in /common_types.json);
its own definitions, as #/… or through a document named catalog.json;
a peer catalog it holds, as <peer document>#/components/… or #/functions/…, where the document names the peer by catalogId or $id, exactly or by path suffix, before falling back to the file name (protocol guide, "Cross-Catalog References").

normalize/2 rewrites references into the common types and into the catalog itself as local #/$defs/… pointers; inline/4 writes local and peer references inline, keeping references to common types.

query/2, inline/4 and strip_envelope/1 also read documents whose objects are Jason.OrderedObjects, and keep their key order.

Summary

Types

peer()

A peer catalog for reference resolution: its ids and its document.

Functions

cross_document?(node)

Whether any $ref in node may point into a peer catalog: one with a document part other than the common types or catalog.json.

def_refs(node)

The names of the $defs that local #/$defs/… references in node target (the first segment after #/$defs/).

externalize(node, common_names, document \\ "common_types.json")

Points local references to the names in common_names at the common types document document (#/$defs/X becomes <document>#/$defs/X).

find_peer(document, peers)

The peer a $ref document names, or nil. Common types and a document named exactly catalog.json never name a peer; a path ending in /catalog.json names one only by id. Otherwise ids are matched first (exactly or by path suffix), then file names; the first match in peers order wins.

inline(node, root, peers, preserved)

Writes the local and peer references of node inline.

localize(ref, peers \\ [])

Rewrites a cross-document $defs reference as a local pointer: one into the common types, into a document named catalog.json, or into a path ending in /catalog.json that names none of peers. Any other reference is returned unchanged.

names_document?(document, name)

Whether the document part of a $ref is the file name or a path ending in it.

normalize(node, peers \\ [])

Applies localize/2 to every $ref in node.

own_def_name(ref)

The $defs name a reference into the same catalog targets: a local #/$defs/X, or a pointer into a catalog.json document.

own_def_refs(node)

Like def_refs/1, also counting references into a catalog.json document, which a catalog uses for its own definitions.

query(document, arg2)

The node a #/… JSON pointer addresses in document, or nil.

reachable_defs(roots, defs)

The names in defs that roots reference, transitively (counting references into catalog.json).

strip_envelope(schema)

Removes a component's envelope (id, component and catalogId properties and required names) and closure keywords, recursively through allOf, where the members that declare component move first.

Types

peer()

(since 0.1.0)

@type peer() :: %{
  catalog_id: String.t() | nil,
  schema_id: String.t() | nil,
  document: map()
}

A peer catalog for reference resolution: its ids and its document.

Functions

cross_document?(node)

(since 0.1.0)

@spec cross_document?(term()) :: boolean()

Whether any $ref in node may point into a peer catalog: one with a document part other than the common types or catalog.json.

def_refs(node)

(since 0.1.0)

@spec def_refs(term()) :: MapSet.t(String.t())

The names of the $defs that local #/$defs/… references in node target (the first segment after #/$defs/).

externalize(node, common_names, document \\ "common_types.json")

(since 0.1.0)

@spec externalize(term(), MapSet.t(String.t()), String.t()) :: term()

Points local references to the names in common_names at the common types document document (#/$defs/X becomes <document>#/$defs/X).

find_peer(document, peers)

(since 0.1.0)

@spec find_peer(String.t(), [peer()]) :: peer() | nil

inline(node, root, peers, preserved)

(since 0.1.0)

@spec inline(term(), map(), [peer()], MapSet.t(String.t())) :: term()

Writes the local and peer references of node inline.

A #/… reference is replaced by its target in root, with the keys beside the $ref merged over it; a reference into a peer (see find_peer/2) by its target in the peer's document, whose own local references resolve against that document. A reference to a name in preserved (the common types) stays, and so does a reference that is already being expanded or whose target is missing. A whole component inherited through #/components/<Name> loses its envelope (id, component, catalogId) and closure keywords.

localize(ref, peers \\ [])

(since 0.1.0)

@spec localize(String.t(), [peer()]) :: String.t()

names_document?(document, name)

(since 0.1.0)

@spec names_document?(String.t(), String.t()) :: boolean()

Whether the document part of a $ref is the file name or a path ending in it.

normalize(node, peers \\ [])

(since 0.1.0)

@spec normalize(term(), [peer()]) :: term()

Applies localize/2 to every $ref in node.

own_def_name(ref)

(since 0.1.0)

@spec own_def_name(term()) :: String.t() | nil

The $defs name a reference into the same catalog targets: a local #/$defs/X, or a pointer into a catalog.json document.

own_def_refs(node)

(since 0.1.0)

@spec own_def_refs(term()) :: MapSet.t(String.t())

Like def_refs/1, also counting references into a catalog.json document, which a catalog uses for its own definitions.

query(document, arg2)

(since 0.1.0)

@spec query(term(), String.t()) :: term()

The node a #/… JSON pointer addresses in document, or nil.

reachable_defs(roots, defs)

(since 0.1.0)

@spec reachable_defs([term()], map()) :: MapSet.t(String.t())

The names in defs that roots reference, transitively (counting references into catalog.json).

strip_envelope(schema)

(since 0.1.0)

@spec strip_envelope(map()) :: map()