diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml new file mode 100644 index 0000000..067454e --- /dev/null +++ b/.github/workflows/build.yaml @@ -0,0 +1,24 @@ +on: + push: + branches: + - "*" + +jobs: + publish: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: docker-practice/actions-setup-docker@1.0.4 + - run: make build + - uses: actions/upload-artifact@v2 + with: + name: specs + path: "**/index.html" + - name: GitHub Pages + if: ${{ github.ref == 'refs/heads/master' }} + uses: crazy-max/ghaction-github-pages@v2.1.1 + with: + build_dir: . + jekyll: false + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..dcaf716 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +index.html diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..fadbc25 --- /dev/null +++ b/Makefile @@ -0,0 +1,16 @@ +watch: + docker-compose run --rm bikeshed watch /extensions/$(spec)/index.bs + +define build-target + docker-compose run --rm bikeshed spec /extensions/$1 +endef + +build: + @for f in $(shell find . -name "*.bs"); do \ + echo "Building $${f}"; \ + $(call build-target,$${f}); \ + done + +new: + mkdir -p $(spec) + docker-compose run --rm bikeshed template > $(spec)/index.bs diff --git a/README.md b/README.md index 088443e..94350a5 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,13 @@ # Hydra extensions This repository gathers vocabularies which extend [Hydra Core](http://www.hydra-cg.com/spec/latest/core/) to allow implementors to create richer hypermedia in their Hydra APIs. + +## Adding extensions + +Simply run `make new spec=my-extension` and commit the created `index.bs` file. + +## Run locally + +Run `make watch spec=my-extension` to start bikeshed in observing mode. It will generate an adjacent `index.html` when the source changes. + +Run `make build` to generate all specification files. diff --git a/bs.Dockerfile b/bs.Dockerfile new file mode 100644 index 0000000..224706f --- /dev/null +++ b/bs.Dockerfile @@ -0,0 +1,7 @@ +FROM python:buster + +RUN pip install bikeshed==2.4.4 +RUN bikeshed update + +ENTRYPOINT ["bikeshed"] +CMD ["--help"] diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..f793ad6 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,8 @@ +version: "3" +services: + bikeshed: + build: + context: . + dockerfile: bs.Dockerfile + volumes: + - .:/extensions diff --git a/shacl/index.bs b/shacl/index.bs new file mode 100644 index 0000000..4009b4a --- /dev/null +++ b/shacl/index.bs @@ -0,0 +1,83 @@ +
+Title: Hydra-SHACL Interoperability +Shortname: hashi +Level: 1 +Status: LD +Group: HydraCG +URL: https://hydracg.github.io/extensions/shacl +Editor: Tomasz Pluskiewicz, Zazuko GmbH https://zazuko.com/, https://t-code.pl +Abstract: This document provides additional terms and examples of using SHACL together with Hydra to describe API's hyperemedia +Markup Shorthands: markdown yes ++ +
+{ + "hydra": { + "authors": [ + "Markus Lanthaler" + ], + "href": "http://www.hydra-cg.com/spec/latest/core/", + "title": "Hydra Core Vocabulary", + "status": "UD", + "publisher": "W3C" + } +} ++ +# Introduction # {#intro} + +[[!Hydra|Hydra Core]] vocabulary does define a handful of data modeling terms such as `hydra:Class` and `hydra:supportedProperty` which can be used to build basic APIs. However, it was never a goal of Hydra Core to become a full-blown modeling language, given available alternatives. + +One such alternative is [[!SHACL]], which is defined by its authors as "a language for validating RDF graphs against a set of conditions", yet its usefulness goes way beyond just data validation. See the [[shacl-ucr|SHACL Use Cases and Requirements]] note for various ideas for employing [[SHACL]]. + +In this document we propose various ways in which [[SHACL]] can be used by both Hydra API publishers and consumers to facilitate client-server interaction. + +# Conventions # {#conventions} + +The base namespace of this extension and its unique identifier is `http://www.w3.org/ns/hydra/shacl#`. + +The preferred prefix is `hashi:`. + +# Announcing the extension # {#announcing} + +Conforming with the [[Hydra#extensions|Extensions]] section of [[Hydra]], an API MUST announce the use of an extension by adding it to its `hydra:ApiDocumentation`: + +
+ Adding SHACL extension to an API +
+ ++{ + "@context": "http://www.w3.org/ns/hydra/context.jsonld", + "@id": "http://api.example.com/doc/", + "extension": "http://www.w3.org/ns/shacl#" +} ++