{"id":19179490,"url":"https://github.com/hypermedia-app/express-middleware-shacl","last_synced_at":"2025-10-07T00:00:06.921Z","repository":{"id":42029297,"uuid":"355464636","full_name":"hypermedia-app/express-middleware-shacl","owner":"hypermedia-app","description":"Express middleware which validates request bodies using SHACL Shapes","archived":false,"fork":false,"pushed_at":"2024-03-29T09:05:10.000Z","size":425,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-04T19:46:33.963Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hypermedia-app.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-07T08:13:46.000Z","updated_at":"2021-11-08T11:25:42.000Z","dependencies_parsed_at":"2024-11-09T10:44:08.062Z","dependency_job_id":"2f3cb742-2ae2-494d-80c0-22184b9e7110","html_url":"https://github.com/hypermedia-app/express-middleware-shacl","commit_stats":{"total_commits":48,"total_committers":3,"mean_commits":16.0,"dds":"0.41666666666666663","last_synced_commit":"b610fd40da831393d4583e3b32e7d60f52ecbee7"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":"tpluscode/ts-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypermedia-app%2Fexpress-middleware-shacl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypermedia-app%2Fexpress-middleware-shacl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypermedia-app%2Fexpress-middleware-shacl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypermedia-app%2Fexpress-middleware-shacl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hypermedia-app","download_url":"https://codeload.github.com/hypermedia-app/express-middleware-shacl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240258116,"owners_count":19772969,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T10:43:19.712Z","updated_at":"2025-10-07T00:00:01.853Z","avatar_url":"https://github.com/hypermedia-app.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# express-middleware-shacl\n\nExpress middleware which validates request bodies using SHACL Shapes\n\nUses [rdf-validate-shacl](https://npm.im/rdf-validate-shacl) to create the validation report.\n\nIf validation fails, returns an [RFC 7807](https://tools.ietf.org/html/rfc7807) Problem Details\ndocument extended to be valid JSON-LD resource.\n\n## Setup\n\nThe package exports a factory to create an express middleware handler. One parameter is required:\n\n```typescript\nimport express from 'express'\nimport { shaclMiddleware } from 'express-middleware-shacl'\nimport { rdf } from '@tpluscode/rdf-ns-builders'\nimport { NamedNode, DatasetCore } from 'rdf-js' \nimport { loadResources } from './store'\n\nconst app = express()\n\napp.use(shaclMiddleware({\n  // Load the shapes to populate the Shapes Graph.\n  async loadShapes(req: express.Request): Promise\u003cDatasetCore\u003e {\n      // Should at least use the payload resource types but might also select more shapes,\n      // such as any shape annotated on the existing resource in database\n      const types = req.shacl.dataGraph.out(rdf.type).terms\n      \n      // Possible implementation could be a DESCRIBE query\n      /*\n       DESCRIBE ?shape1 ?shape2 ... ?shapeN\n       */\n  },\n  // (Optional) Load rdf:type quads of the given resources\n  loadTypes(resources: NamedNode[], req: express.Request): Promise\u003cDatasetCore\u003e {\n      // For example, could be implemented as a SPARQL query\n      /*\n       CONSTRUCT { ?resource a ?type }\n       WHERE { ?resource a ?type }\n       */\n  }\n}))\n```\n\n## Details\n\nThe middleware works in four stages. Check the sections below for more explanations\n\n1. Create `req.shacl` structure on `Request` object\n2. Load SHACL Shapes needed to validate\n3. Load instance types, if necessary\n4. Run validation\n\n### `req.shacl`\n\nDownstream handlers will have access to `req.shacl`, which is defined as \n\n```typescript\nimport type { AnyPointer } from 'clownface'\n\ninterface Shacl {\n    /**\n     * The requested RDF resources, parsed from body\n     */\n    dataGraph: AnyPointer\n    \n    /**\n     * The loaded Shapes\n     */\n    shapesGraph: AnyPointer\n}\n```\n\nBy default, [express-rdf-resource](https://npm.im/express-rdf-resource) will be used to parse the\nincoming request. This can be changed by adding a custom middleware before SHACL.\n\n```js\nimport express from 'express'\nimport clownface from 'clownface'\n\nconst app = express()\n\napp.use((req, res, next) =\u003e {\n  req.resource = async function() {\n    // an async function which should return a Graph Pointer\n    let dataset\n    \n    return clownface({ dataset })\n  }\n  \n  next()\n})\n\napp.use(shaclMiddleware({\n  // ...\n}))\n```\n\n### Load instance types\n\nConsider a resource with links to another:\n\n```turtle\nprefix schema: \u003chttp://schema.org/\u003e\nbase \u003chttp://example.com/\u003e\n\n\u003cLeonard\u003e a \u003cvocab/Person\u003e ;\n  schema:spouse \u003cPenny\u003e ;\n  schema:knows \u003cHoward\u003e, \u003cSheldon\u003e ;\n.\n```\n\nThe type `\u003cvocab/Person\u003e` may be a shape which requires the object of `schema:spouse` and\n`schema:knows` to also be an instances of the same type:\n\n```turtle\nprefix rdfs: \u003chttp://www.w3.org/2000/01/rdf-schema#\u003e\nprefix sh: \u003chttp://www.w3.org/ns/shacl#\u003e\nprefix schema: \u003chttp://schema.org/\u003e\nbase \u003chttp://example.com/\u003e\n\n\u003cvocab/Person\u003e\n  a rdfs:Class, sh:NodeShape ;\n  sh:property [\n    sh:path schema:spouse ;\n    sh:class \u003cvocab/Person\u003e ;\n  ] , [\n    sh:path schema:knows ;\n    sh:class \u003cvocab/Person\u003e ;\n  ] ;\n.\n```\n\nAs-is, validation of the resource `\u003cLeonard\u003e` will fail because a SHACL validation library will not\nbe able to verify that the linked resources also have the correct RDF type.\n\nGiven such shapes, it will be necessary to provide an implementation of the `loadTypes` function. As\nmentioned above, it could be implemented as SPARQL Construct. In a simplest case, when the store's\ndefault graph would be queried fo all data, that query could be as simple as:\n\n```sparql\nbase \u003chttp://example.com/\u003e\n\nCONSTRUCT { ?instance a ?type }\nWHERE {\n  VALUES ?instance {\n    # iterate the array passed to loadTypes\n    \u003cPenny\u003e \u003cHoward\u003e \u003cSheldon\u003e\n  }\n\n  ?instance a ?type .\n}\n```\n\n### Validation run\n\nIf the `req.shacl.shapesGraph` dataset is empty, the next middleware will be called.\n\nIf there are shapes in `req.shacl.shapesGraph` but none of them have a target matching the requested\nresources, `Bad Request` will be the response. This is to prevent false-positives, in case when the \npayload would be completely unrelated to the shapes, thus resuling in no validation actually happening.\nConsidered are:\n\n- [implicit class targets](https://www.w3.org/TR/shacl/#implicit-targetClass)\n- `sh:targetClass`,\n- `sh:targetNode`\n- `sh:targetSubjectsOf`.\n\nIf the validation succeeds (`sh:conforms true`), the next middleware will be called.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypermedia-app%2Fexpress-middleware-shacl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhypermedia-app%2Fexpress-middleware-shacl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypermedia-app%2Fexpress-middleware-shacl/lists"}