{{/*

Handles OpenAPI "Reference Objects".

Reference objects are JSON objects with a single property, `$ref` (and
optionally a `summary` and `description`). This partial resolves the reference
and returns the expanded object.

The input parameter is a dict with the following keys:

* `schema`: A schema object to check for $ref properties.

* `path`: The path of the schema file containing the (potential) ref; used for resolving
  relative references.

Ref: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#reference-object.

*/}}

{{ $schema := .schema }}
{{ $path := .path }}

{{ $ret := $schema }}

{{ $ref_value := index $schema "$ref"}}
{{ if $ref_value }}
    {{/* Resolve the ref URI relative to the path of the schema file */}}
    {{ $base_uri := urls.Parse $path }}
    {{ $ref_uri := urls.Parse $ref_value }}
    {{ $full_uri := $base_uri.ResolveReference $ref_uri }}

    {{/* strip the extension, and the leading `/`, from the path */}}
    {{ $full_path := strings.TrimPrefix "/" (replaceRE "\\.[^\\.]*$" "" $full_uri.Path) }}

    {{ $pieces := split $full_path "/" }}
    {{ $ret = index site.Data $pieces }}

    {{ if $ref_uri.Fragment }}
        {{/*
        Per https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relative-references-in-uris:

        > If a URI contains a fragment identifier, then the fragment should
        > be resolved per the fragment resolution mechanism of the
        > referenced document. If the representation of the referenced
        > document is JSON or YAML, then the fragment identifier SHOULD be
        > interpreted as a JSON-Pointer as per RFC6901.

        RFC6901, in a nutshell, says the pointer is a series of keys
        separated by `/`. We strip off the leading `/` and use the
        subsequent keys as indexes.
        */}}

        {{ $keys := split (strings.TrimPrefix "/" $ref_uri.Fragment ) "/" }}
        {{ $ret = index $ret $keys }}
    {{ end }}

    {{/*
    OpenAPI spec says that "summary" and "description" from the reference object override
    the values from the referenced component.
    */}}
    {{ if isset $schema "summary" }}
        {{ $ret = merge $ret (dict "summary" $schema.summary) }}
    {{ end }}
    {{ if isset $schema "description" }}
        {{ $ret = merge $ret (dict "description" $schema.summary) }}
    {{ end }}
{{ end }}

{{ return $ret }}