Merge pull request #8 from HydraCG/shacl

SHACL

.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/[email protected]
+    - 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/[email protected]
+      with:
+        build_dir: .
+        jekyll: false
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1 @@
+index.html

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

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.

bs.Dockerfile

@@ -0,0 +1,7 @@
+FROM python:buster
+
+RUN pip install bikeshed==2.4.4
+RUN bikeshed update
+
+ENTRYPOINT ["bikeshed"]
+CMD ["--help"]

docker-compose.yml

@@ -0,0 +1,8 @@
+version: "3"
+services:
+  bikeshed:
+    build:
+      context: .
+      dockerfile: bs.Dockerfile
+    volumes:
+    - .:/extensions

shacl/index.bs

@@ -0,0 +1,83 @@
+<pre class='metadata'>
+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
+</pre>
+
+<pre class=biblio>
+{
+	"hydra": {
+		"authors": [
+			"Markus Lanthaler"
+		],
+		"href": "http://www.hydra-cg.com/spec/latest/core/",
+		"title": "Hydra Core Vocabulary",
+		"status": "UD",
+		"publisher": "W3C"
+	}
+}
+</pre>
+
+# 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`:
+
+<div class='example'>
+    <p>
+        Adding SHACL extension to an API
+    </p>
+
+<pre highlight="json" line-highlight="4">
+{
+  "@context": "http://www.w3.org/ns/hydra/context.jsonld",
+  "@id": "http://api.example.com/doc/",
+  "extension": "http://www.w3.org/ns/shacl#"
+}
+</pre>
+</div>
+
+# Extending a Hydra API # {#usage}
+
+## Using Node Shapes to describe request payloads ## {#expects}
+
+Issue(9): Node Shapes used as objects of `hydra:expects`
+
+## Discovering shapes ## {#discovery}
+
+Issue(10): Add a specialized property to link to a collection of shapes
+
+## Providing choices to properties ## {#linking}
+
+Provide choices for properties rendered in a form as `dash:EnumSelectEditor` and `dash:InstancesSelectEditor`.
+
+### Using `hydra:collection` ### {#property-collection}
+
+Issue(11): Static choices
+
+### Using `hydra:search` ### {#property-search}
+
+Issue(11): Filtered choices
+
+# SHACL Shapes for Hydra Core terms # {#shapes}
+
+Issue(12): Model the Hydra Core vocabulary as node shapes