Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix #89: Better README #107

Merged
merged 1 commit into from
Apr 3, 2024
Merged

Fix #89: Better README #107

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/gh-pages-workflow.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: CI
name: Main TREE CG Spec
on:
workflow_dispatch: {}
pull_request: {}
Expand Down
59 changes: 15 additions & 44 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,54 +1,25 @@
<img src="tree-logo.svg" alt="TREE logo" width="400px"/>

__Exposing your Linked Datasets in hypermedia collections__
[Read the spec](https://w3id.org/tree/specification)

ᴛʀᴇᴇ enables you to describe relations between a specific value and all members a page linked from this current page.
Using this specific relation, a script or autonomous query client (such as [Comunica](https://comunica.linkeddatafragments.org/) and [Planner.js](https://planner.js.org)) can understand whether following the link will be useful or not.
The ᴛʀᴇᴇ hypermedia specification enables data publishers and API developers to describe datasets as collections of entity descriptions (a set of quads), called “members”.
One or more views of this collection can be created.
A view allows organizing the members into multiple pages or nodes, and these nodes are interlinked using relations and/or search forms.
This way, a user agent that can interpret the ᴛʀᴇᴇ hypermedia controls can find the most efficient way to the members of interest.

Build the spec using [bikeshed](https://tabatkins.github.io/bikeshed/):
```bash
bikeshed watch spec.bs
```
The spec will be built [automatically](.travis.yml) when pushing to master.

## The Vocabulary

Base URI to be used: `https://w3id.org/tree#`.

Preferred prefix: `tree:`.

All newly introduced terms are explained in the [RDF vocabulary](vocabulary.md).

Most important concepts:
* a `tree:Node` is a page that may contain members of a `tree:Collection`
* a node has `tree:relation` entities with links to other nodes. This relation is typed (e.g., `tree:GeospatiallyContainsRelation` or a `tree:PrefixRelation`),
* the relation has a `tree:value` and a `tree:path`. The former is a literal value on which the search term can be compared. The `tree:path` explains to which property of the members of the collection this relation applies.
## The W3C Community Group

## The specification
This specification is managed by the [W3C ᴛʀᴇᴇ Community Group](https://www.w3.org/community/treecg/). You can join [the public mailing list](https://lists.w3.org/Archives/Public/public-treecg/) or [join one of the online meetings](https://calendar.google.com/calendar/u/0/embed?src=4b04fcfb0103a4f96d703b8b8255f15378d5f4729b9083bfc0129b676ae783d1@group.calendar.google.com&ctz=Europe/Brussels).

Available at https://treecg.github.io/specification
The goal of the community group is to publish a stable and developer-friendly version of the hypermedia specification in 2024. Releases are made after each call, listing the consensus that has been reached during the call.

Mind that a server exposing data with ᴛʀᴇᴇ __must__ [set the CORS headers](http://enable-cors.org) to allow any host.

## Questions and Answers
In case of questions, feel free to contact the current chair [Pieter Colpaert](https://pietercolpaert.be).

### Why publish a hypermedia structure?
## Developing

When a document grows too large for 1 HTTP response, we need to fragment it. The way we fragment it will immediatly decide what queries will be fast and which queries will be slow.
Hypermedia can be used to hit the sweet spot between data dumps and querying APIs (such as GraphQL or SPARQL). It is particularly a sweet spot for Open Data publishers that need a cost-efficient way of publishing their data, while allowing third parties to create serverless applications to reuse the data.

| | dump | ᴛʀᴇᴇ fragments | query |
|:-:|:-:|:-:|:-:|
| processing | client | shared | server |
| server cost | low | okay | high |
| client cost | high | okay | low |
| caching | low | high | low |
| query execution control | high | high | low |

### Why hypermedia?

When you write a client for one server, you can get away with hard-coding the way the API is built based on the API specification. When building a client for the entire Web, we need to make very general specifications that still allow our client to understand what it can do next. The latter are called the hypermedia controls.

### What are triples? JSON-LD? RDF? URIs? Linked Data?
Build the spec using [bikeshed](https://tabatkins.github.io/bikeshed/):
```bash
bikeshed watch spec.bs
```
The spec will be built [automatically](.github/workflows/) when pushing to the master branch.

Same idea as hypermedia, only for understanding the elements in the pages itself. See [these intro slides](https://speakerdeck.com/pietercolpaert/an-introduction-to-open-data), or [read this chapter](https://phd.pietercolpaert.be/chapters/data-and-interoperability).
Loading