Library to manage Resource references using URI and JSON Pointer.

The JSONRef class in the kjson-pointer library provides a means of navigating around a JSON or YAML structure.

The resource-loader library simplifies the process of loading resources identified by URL, including the managing of relative URLs.

The resource-ref library brings these together and provides a concise API for navigating structures of related JSON or YAML resources.

First, get an instance of RefResourceLoader:

    val loader = RefResourceLoader()

Then, you can get a Resource in one of a number of ways:

    val fileResource = loader.resource(File("path.to.file"))                             // using java.io.File
    val pathResource = loader.resource(FileSystems.getDefault().getPath("path.to.file")) // using java.nio.file.Path
    val urlResource = loader.resource(URL("https://example.com/resource"))               // using java.net.URL
    val classpathResource = loader.resource(Resource.classPathURL("path.to.file")!!)     // using classpath

The ref() extension function on the Resource will load the resource as JSON, or if it has an extension of .yaml or .yml, or it is an HTTP(S) resource with a MIME type containing "yaml" or "yml" (there is no official MIME type for YAML) it will load the resource as YAML, and return a ResourceRef<JSONObject>.

    val ref = resource.ref()

The ResourceRef has two properties (both publicly accessible):

• resource: the Resource from which the data was loaded – this allows navigation between resources using the rules specified by RFC-3986, and
• ref: the JSONRef pointing to the identified location in the structure – this allows navigation within the resource.

The ResourceRef object is immutable – any navigation functions such as resolve(destination) etc. will return a new ResourceRef.

Most of the functions available on JSONRef and also available on ResourceRef, for example child(), parent(), optionalString() etc. (see JSONRef for more details), but because the ResourceRef also carries the URL used to locate the resource, error messages will be much more helpful.

And the ResourceRef also has the function that combines the two areas of functionality – the resolve() function will take a relative reference of the form "resource#node" and return a new ResourceRef pointing to the specified location.

    val targetRef = ref.resolve(destination)

There are three possibilities:

1. Relative URI with no fragment (the part following the "#" sign) – in this case the function will attempt to locate the resource identified by the relative URI using RFC-3986, and return a ResourceRef pointing to the root of the object.
2. A relative URI with a fragment – the function will attempt to locate the resource as above, and will return a new ResourceRef with the pointer set to the node identified by the fragment, as a JSON Pointer.
3. A fragment (with preceding "#" sign) only – the function will return a new ResourceRef for the current resource, with the pointer set to the node identified by the fragment.

More documentation to follow…

The latest version of the library is 1.5, and it may be obtained from the Maven Central repository.

    <dependency>
      <groupId>io.kjson</groupId>
      <artifactId>resource-ref</artifactId>
      <version>1.5</version>
    </dependency>

    implementation 'io.kjson:kjson-pointer:1.5'

    implementation("io.kjson:kjson-pointer:1.5")

Peter Wall

2024-02-25