https://github.com/qbicsoftware/compass
A Java library to validate FAIR signposting profiles of web links.
https://github.com/qbicsoftware/compass
Last synced: 6 months ago
JSON representation
A Java library to validate FAIR signposting profiles of web links.
- Host: GitHub
- URL: https://github.com/qbicsoftware/compass
- Owner: qbicsoftware
- License: agpl-3.0
- Created: 2025-12-02T08:45:31.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-01-12T15:53:18.000Z (6 months ago)
- Last Synced: 2026-01-12T21:42:07.114Z (6 months ago)
- Language: Groovy
- Size: 147 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.CFF
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# Compass
Java library for FAIR Signposting validation of RFC 8288 Web Links.
[](https://github.com/qbicsoftware/compass/actions/workflows/build_package.yml)
[](https://github.com/qbicsoftware/compass/actions/workflows/run_tests.yml)
[](https://github.com/qbicsoftware/compass/actions/workflows/codeql-analysis.yml)
[](https://github.com/qbicsoftware/compass/releases)
[](https://github.com/qbicsoftware/compass/blob/main/LICENSE)
[](https://codecov.io/github/qbicsoftware/compass)
[](https://sonarcloud.io/summary/new_code?id=qbicsoftware_compass)
[](https://sonarcloud.io/summary/new_code?id=qbicsoftware_compass)
---
## ⚠️ Development Status
This repository is in an **early and experimental stage**.
- APIs may change or be removed without prior notice
- Documentation may be incomplete or outdated
- Backward compatibility is **not guaranteed**
Use at your own risk, but provide feedback and suggestions in an issue or contribution in form of a pull-request.
---
# Quick start
## Resolve dependency
```xml
life.qbic
compass
1.0.0
```
Check the latest component version on [Maven Central](https://central.sonatype.com/artifact/life.qbic/compass/).
## Example: Level 1 FAIR Signposting Profile validation
```bash
curl -I https://zenodo.org/records/17179862
```
A simple HTTP GET request to the [Zenodo record](https://zenodo.org/records/17179862) will result in the following HTTP header:
Full HTTP Link header returned by Zenodo (real-world example)
```http
HTTP/1.1 200 OK
server: nginx
date: Mon, 01 Dec 2025 12:14:33 GMT
content-type: text/html; charset=utf-8
content-length: 85404
vary: Accept-Encoding
link: ; rel="author" , ; rel="author" , ; rel="author" , ; rel="cite-as" , ; rel="describedby" ; type="application/dcat+xml" , ; rel="describedby" ; type="application/json" , ; rel="describedby" ; type="application/ld+json" , ; rel="describedby" ; type="application/ld+json;profile="https://datapackage.org/profiles/2.0/datapackage.json"" , ; rel="describedby" ; type="application/marcxml+xml" , ; rel="describedby" ; type="application/vnd.citationstyles.csl+json" , ; rel="describedby" ; type="application/vnd.datacite.datacite+json" , ; rel="describedby" ; type="application/vnd.datacite.datacite+xml" , ; rel="describedby" ; type="application/vnd.geo+json" , ; rel="describedby" ; type="application/vnd.inveniordm.v1+json" , ; rel="describedby" ; type="application/vnd.inveniordm.v1.full+csv" , ; rel="describedby" ; type="application/vnd.inveniordm.v1.simple+csv" , ; rel="describedby" ; type="application/x-bibtex" , ; rel="describedby" ; type="application/x-dc+xml" , ; rel="describedby" ; type="text/x-bibliography" , ; rel="item" ; type="application/pdf" , ; rel="item" ; type="application/octet-stream" , ; rel="item" ; type="application/octet-stream" , ; rel="license" , ; rel="type" , ; rel="type" , ; rel="linkset" ; type="application/linkset+json"
```
For the sake of simplicity and to show the FAIR signposting use case Level 1, we use only
some of the link targets:
- the author
- the citation
- the record API endpoint for additional meta-data
```java
import life.qbic.compass.SignPostingProcessor;
import life.qbic.compass.model.SignPostingView;
import life.qbic.linksmith.core.WebLinkProcessor;
import life.qbic.linksmith.spi.WebLinkValidator.ValidationResult;
// Raw header of an HTTP response with link attribute
// 'link: ; rel="author" , ; rel="author"'
String rawHeader =
' ; rel="author" , ; rel="cite-as" , ; rel="describedby" ; type="application/json"';
WebLinkProcessor webLinkProcessor = new WebLinkProcessor.Builder().build();
ValidationResult result = webLinkProcessor.process(rawHeader);
// Investigate the validation result
// ...
// Fetch the weblinks and let compass process them
// Default builds to FAIR Signposting Level 1 validation
SignPostingProcessor processor = new SignPostingProcessor.Builder().build();
SignPostingResult signPostResult = processor.process(result.weblinks());
if(signPostResult.containsIssues()){
// Retrieve the report
var report = result.report();
// Investigate the report
// ...
return;
}
SignPostingView view = signPostResult.signPostingView();
// Access to cite-as typed WebLinks
List citeAs = view.citeAs();
// Access to describedby typed WebLinks
List metadata = view.describedBy();
// Access to author typed WebLinks
List authors = view.author();
```
## What is Compass?
**Compass** is a lightweight Java library for **validating and interpreting FAIR Signposting**.
It builds on [Linksmith](https://github.com/qbicsoftware/linksmith) and adds:
- defensive [RFC 8288](https://datatracker.ietf.org/doc/html/rfc8288) *model-level* validation,
- [FAIR Signposting](https://signposting.org/FAIR/) Level 1 and Level 2 recipe validation,
- semantic views and Link Set ([RFC 9264](https://www.rfc-editor.org/rfc/rfc9264.html)) processing.
Compass operates entirely **in memory**, performs **no network requests**,
and works with `WebLink` objects regardless of how they were created.
## Why Compass?
| Without Compass | With Compass |
|-----------------|--------------|
| Assume WebLinks are well-formed | Defensive validation of RFC 8288 *model invariants* |
| Validation tied to parsing strategy | Validation independent of how WebLinks were created |
| Manual inspection of `rel` values and parameters | Semantic views for Landing Pages, Metadata Resources, and Content Resources |
| No clear distinction between Level 1 and Level 2 Signposting | Explicit validators for Level 1 and Level 2 recipes |
| Link Sets parsed and interpreted ad-hoc | Ready-to-use parsers for RFC 9264 Link Set formats |
| Ambiguous handling of multiple Link Sets | Pluggable aggregation strategies with defined semantics |
| Validation logic scattered across client code | Centralized, reusable Signposting validation pipeline |
## How Compass fits in
Compass is designed to complement — not replace — Linksmith:
- **Linksmith**
- Parses Web Linking syntax
- Validates [RFC 8288](https://datatracker.ietf.org/doc/html/rfc8288) during parsing
- Produces `WebLink` model objects
- **Compass**
- Does not assume how `WebLink`s were produced
- Validates [RFC 8288](https://datatracker.ietf.org/doc/html/rfc8288) *model-level constraints* defensively
- Applies [FAIR Signposting](https://signposting.org/FAIR/) semantics and recipes
- Interprets Level 2 Link Sets ([RFC 9264](https://www.rfc-editor.org/rfc/rfc9264.html))
Together, they form a clean separation of concerns:
- *Linksmith*: “Is this syntactically valid Web Linking?”
- *Compass*: “Is this WebLink model sound, and what does it mean for FAIR Signposting?”