diff --git a/README.md b/README.md index 893fe70..e83c66e 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,49 @@ A browser-based client for FAIR Data Point (FDP) administration. +## Background + +### FAIR principles + +The [FAIR principles] aim to make _data_ more **F**indable, **A**ccessible, **I**nteroperable, and **R**eusable. + +### FAIR Data Point (FDP) + +#### Purpose + +A FAIR Data Point (FDP) is a tool for the publication of **_metadata_** describing datasets in a standardized form that unlocks the powers of [Semantic Web] technology. +The FDP uses the Resource Description Framework ([RDF]) and the Data Catalog Vocabulary ([DCAT]) to facilitate publication of metadata as [Linked (Open) Data], following the [FAIR principles]. + +[RDF] describes _things_ using statements of the form `(, , )`, called triples. +Together, these triples define a knowledge graph where the `` and `` terms represent nodes and the `` terms represent edges. +By storing metadata, in the form of RDF, in a [triple store], a type of graph database specialized for handling [RDF], an FDP gains the ability to perform advanced queries using the [SPARQL] query language. + +Due to the use of [Semantic Web] technology, metadata published on an FDP becomes part of a world wide web of knowledge. +This enables people and machines from around the globe to explore the metadata and discover relations between different datasets using logical inference and reasoning techniques. + +#### Specification + +The requirements for the [RDF] representation of FAIR Data Point metadata are defined in the [FDP 1.2 specification]. +Compliance with the [FDP 1.2 specification] specification implies the following: + +1. The FDP root URL must resolve to a metadata description of the FDP itself as a [DCAT] `MetadataService`. + This description must include a link to the FDP's primary API endpoint, indicated by `dcat:endpointURL`. +2. The FDP must expose metadata in the form of [RDF], supporting at least the [Turtle] (default) and [JSON-LD] representations. +3. Each metadata record on an FDP should be linked to a "profile" which points to a metadata schema, expressed in the Shapes Constraint Language ([SHACL]), that can be used for validation. +4. FDP metadata schemas must have (a subclass of) [DCAT] `Resource` as the target class. +5. The FDP metadata must include Linked Data Platform ([LDP]) containment statements. + +The [FDP 1.2 specification] also mentions that the FDP must provide an API following [REST] guidelines so that a client is able to discover the available actions and access the resources it needs. + +#### Reference implementation and API + +The [FDP reference implementation] is a Java-based implementation of the [FDP 1.2 specification] that provides an HTTP API for manipulating and querying RDF metadata. +This enables users, like data stewards, to build automated metadata publication workflows for the FDP. +The FDP API is intended primarily for machine interaction and exposes machine-readable documentation based on the [OpenAPI 3 spec]. +The FDP reference implementation also provides a [swagger-ui] interface that allows humans to explore the API using a web browser. +However, direct human interaction with the FDP API can still be a bit cumbersome. +To simplify direct human interaction with the FDP API, we offer the FDP client. + ## FAIR Data Point Client The FAIR Data Point (FDP) _client_ provides a web-based user interface that makes it easier for humans to interact with a FAIR Data Point by hiding the interactions with the FDP API. @@ -105,6 +148,7 @@ For example, you could use this to point the client to an actual FDP on the web, Note that the `config.local.json` file is ignored by `git`. +[FDP reference implementation]: https://github.com/FAIRDataTeam/FAIRDataPoint [legacy FDP client]: https://github.com/FAIRDataTeam/FAIRDataPoint-client [FDP 1.2 specification]: https://specs.fairdatapoint.org [FAIRDataTeam/compose]: https://github.com/FAIRDataTeam/compose/tree/master/fdp/ephemeral/v1/dev/fdp-client-redux @@ -118,6 +162,21 @@ Note that the `config.local.json` file is ignored by `git`. [dotenv]: https://github.com/motdotla/dotenv [vite docs]: https://vite.dev/guide/env-and-mode#env-files [fairdata/fairdatapoint-client-redux]: https://hub.docker.com/r/fairdata/fairdatapoint-client-redux +[RDF]: https://www.w3.org/TR/rdf12-primer/ +[DCAT]: https://www.w3.org/TR/vocab-dcat-3/ +[SPARQL]: https://www.w3.org/TR/sparql11-query/ +[Linked (Open) Data]: https://www.w3.org/DesignIssues/LinkedData +[FAIR principles]: https://doi.org/10.1038/sdata.2016.18 +[Nginx hardened image]: https://hub.docker.com/hardened-images/catalog/dhi/nginx +[triple store]: https://opendatahandbook.org/glossary/en/terms/triple-store/ +[Semantic Web]: https://www.w3.org/2001/sw/SW-FAQ +[Turtle]: https://www.w3.org/TR/rdf12-turtle/ +[JSON-LD]: https://json-ld.org/primer/latest/ +[SHACL]: https://www.w3.org/TR/shacl/ +[LDP]: https://www.w3.org/TR/ldp/ +[OpenAPI 3 spec]: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.2.0.md +[REST]: https://roy.gbiv.com/pubs/dissertation/rest_arch_style.htm [Nginx hardened image]: https://hub.docker.com/hardened-images/catalog/dhi/nginx [Docker Compose]: https://docs.docker.com/compose/ [Fetch API]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API +[swagger-ui]: https://swagger.io/open-source/swagger-ui/