{"id":22750060,"url":"https://github.com/pwall567/resource-ref","last_synced_at":"2025-03-30T06:21:57.456Z","repository":{"id":211883783,"uuid":"730171602","full_name":"pwall567/resource-ref","owner":"pwall567","description":"Library to manage Resource references using URI and JSON Pointer","archived":false,"fork":false,"pushed_at":"2025-02-09T01:44:12.000Z","size":74,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-04T18:03:16.828Z","etag":null,"topics":["json","json-pointer","kotlin","url"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pwall567.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-11T11:01:49.000Z","updated_at":"2025-02-09T01:43:51.000Z","dependencies_parsed_at":"2023-12-11T13:01:29.680Z","dependency_job_id":"f80eca04-6fbc-4d77-ba2b-29692e117028","html_url":"https://github.com/pwall567/resource-ref","commit_stats":null,"previous_names":["pwall567/resource-ref"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwall567%2Fresource-ref","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwall567%2Fresource-ref/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwall567%2Fresource-ref/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwall567%2Fresource-ref/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pwall567","download_url":"https://codeload.github.com/pwall567/resource-ref/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246282700,"owners_count":20752439,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json","json-pointer","kotlin","url"],"created_at":"2024-12-11T04:11:51.633Z","updated_at":"2025-03-30T06:21:57.450Z","avatar_url":"https://github.com/pwall567.png","language":"Kotlin","readme":"# resource-ref\n\n[![Build Status](https://github.com/pwall567/resource-ref/actions/workflows/build.yml/badge.svg)](https://github.com/pwall567/resource-ref/actions/workflows/build.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Kotlin](https://img.shields.io/static/v1?label=Kotlin\u0026message=v2.0.21\u0026color=7f52ff\u0026logo=kotlin\u0026logoColor=7f52ff)](https://github.com/JetBrains/kotlin/releases/tag/v2.0.21)\n[![Maven Central](https://img.shields.io/maven-central/v/io.kjson/resource-ref?label=Maven%20Central)](https://central.sonatype.com/artifact/io.kjson/resource-ref)\n\nLibrary to manage Resource references using [URI](https://www.rfc-editor.org/info/rfc3986) and\n[JSON Pointer](https://tools.ietf.org/html/rfc6901).\n\n## Background\n\nThe `JSONRef` class in the [`kjson-pointer`](https://github.com/pwall567/kjson-pointer) library provides a means of\nnavigating around a JSON or YAML structure.\n\nThe [`resource-loader`](https://github.com/pwall567/resource-loader) library simplifies the process of loading resources\nidentified by URL, including the managing of relative URLs.\n\nThe `resource-ref` library brings these together and provides a concise API for navigating structures of related JSON or\nYAML resources.\n\n## Quick Start\n\n### `RefResourceLoader`\n\nFirst, get an instance of `RefResourceLoader` (a form of `ResourceLoader` that will load JSON or YAML files):\n```kotlin\n    val loader = RefResourceLoader()\n```\n\n### `Resource`\n\nThen, you can get a `Resource` in one of a number of ways:\n```kotlin\n    val fileResource = loader.resource(File(\"path.to.file\"))                             // using java.io.File\n    val pathResource = loader.resource(FileSystems.getDefault().getPath(\"path.to.file\")) // using java.nio.file.Path\n    val urlResource = loader.resource(URL(\"https://example.com/resource\"))               // using java.net.URL\n    val classpathResource = loader.resource(Resource.classPathURL(\"path.to.file\")!!)     // using classpath\n```\n\nIn the case of `RefResourceLoader`, the `Resource` will be a `Resource\u003cJSONValue?\u003e`.\n\nThe `Resource` is not the resource itself, but an object providing:\n- access to the resource by means of the `load()` function\n- navigation to child, parent and sibling resources using the `resolve()` function\n\n### `ResourceRef`\n\nThe `ref()` extension function on the `Resource` will load the resource as JSON, or if it has an extension of `.yaml` or\n`.yml`, or it is an HTTP(S) resource with a MIME type containing \"yaml\" or \"yml\" (the proposed official MIME type for\nYAML is not yet in widespread use) it will load the resource as YAML, and return a `ResourceRef` of the type specified\nto the `ref()` function or implied by the context.\n```kotlin\n    val ref: ResourceRef\u003cJSONObject\u003e = resource.ref()\n```\n\nThe `ResourceRef` has two properties (both publicly accessible):\n- `resource`: the `Resource` from which the data was loaded \u0026ndash; this allows navigation between resources using the\n  rules specified by [RFC-3986](https://www.rfc-editor.org/info/rfc3986), and\n- `ref`: the `JSONRef` pointing to the identified location in the structure \u0026ndash; this allows navigation **within**\n  the resource.\n\nThe `ResourceRef` object is immutable \u0026ndash; any navigation functions such as `resolve(destination)` _etc._ will return\na new `ResourceRef`.\n\nMost of the functions available on `JSONRef` and also available on `ResourceRef`, for example `child()`, `parent()`,\n`optionalString()` _etc._ (see [`JSONRef`](https://github.com/pwall567/kjson-pointer#jsonref) for more details), but\nbecause the `ResourceRef` also carries the URL used to locate the resource, error messages will be much more helpful.\n\n### `resolve()`\n\nAnd the `ResourceRef` also has the function that combines the two areas of functionality \u0026ndash; the `resolve()`\nfunction will take a relative reference of the form \"resource#node\" and return a new `ResourceRef` pointing to the\nspecified location.\n```kotlin\n    val targetRef = ref.resolve\u003cJSONObject\u003e(destination)\n```\n\nThere are three possibilities for the parameter string:\n1. Relative URI with no fragment (the part following the \"`#`\" sign) \u0026ndash; in this case the function will attempt to\n   locate the resource identified by the relative URI using [RFC-3986](https://www.rfc-editor.org/info/rfc3986), and\n   return a `ResourceRef` pointing to the root of the object.\n2. A relative URI with a fragment \u0026ndash; the function will attempt to locate the resource as above, and will return a\n   new `ResourceRef` with the pointer set to the node identified by the fragment, as a\n   [JSON Pointer](https://tools.ietf.org/html/rfc6901).\n3. A fragment (with preceding \"`#`\" sign) only \u0026ndash; the function will return a new `ResourceRef` for the current\n   resource, with the pointer set to the node identified by the fragment.\n\nMore documentation to follow\u0026hellip;\n\n## Dependency Specification\n\nThe latest version of the library is 4.4, and it may be obtained from the Maven Central repository.\n\n### Maven\n```xml\n    \u003cdependency\u003e\n      \u003cgroupId\u003eio.kjson\u003c/groupId\u003e\n      \u003cartifactId\u003eresource-ref\u003c/artifactId\u003e\n      \u003cversion\u003e4.4\u003c/version\u003e\n    \u003c/dependency\u003e\n```\n### Gradle\n```groovy\n    implementation 'io.kjson:kjson-pointer:4.4'\n```\n### Gradle (kts)\n```kotlin\n    implementation(\"io.kjson:kjson-pointer:4.4\")\n```\n\nPeter Wall\n\n2025-03-14\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpwall567%2Fresource-ref","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpwall567%2Fresource-ref","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpwall567%2Fresource-ref/lists"}