{"id":22601650,"url":"https://github.com/nationalarchives/miiify","last_synced_at":"2025-04-11T02:42:13.467Z","repository":{"id":38023752,"uuid":"384707134","full_name":"nationalarchives/miiify","owner":"nationalarchives","description":"A web annotation server built with the same principles as Git","archived":false,"fork":false,"pushed_at":"2024-09-06T13:49:00.000Z","size":415,"stargazers_count":37,"open_issues_count":1,"forks_count":2,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-25T00:30:47.974Z","etag":null,"topics":["annotations","dream","git","iiif","irmin","miiify","ocaml","w3c","web","web-annotation"],"latest_commit_sha":null,"homepage":"","language":"OCaml","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/nationalarchives.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-07-10T13:41:45.000Z","updated_at":"2025-02-25T11:52:09.000Z","dependencies_parsed_at":"2024-02-21T16:51:21.230Z","dependency_job_id":"1d7f1265-6c58-48e0-ad84-ce08ea64197b","html_url":"https://github.com/nationalarchives/miiify","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nationalarchives%2Fmiiify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nationalarchives%2Fmiiify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nationalarchives%2Fmiiify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nationalarchives%2Fmiiify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nationalarchives","download_url":"https://codeload.github.com/nationalarchives/miiify/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248331145,"owners_count":21085848,"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":["annotations","dream","git","iiif","irmin","miiify","ocaml","w3c","web","web-annotation"],"created_at":"2024-12-08T12:16:08.192Z","updated_at":"2025-04-11T02:42:13.442Z","avatar_url":"https://github.com/nationalarchives.png","language":"OCaml","funding_links":[],"categories":["Annotations"],"sub_categories":["Annotation Servers"],"readme":"### Introduction\n\nMiiify is a light-weight web annotation server using an embedded database. Its primary use case is to support [IIIF](https://iiif.io/) applications where it separates the annotation content away from the manifest. This has the advantage of simplifying the manifest and providing persistent access to each annotation through its own unique identifier. Miiify follows the Web Annotation Model and Protocol which means annotations are structured into [containers](https://www.w3.org/TR/annotation-protocol/#annotation-containers). The following [video tutorial](https://miiifystore.s3.eu-west-2.amazonaws.com/presentations/simple-external-annotation.mp4) helps illustrates this and how the server can interact with a IIIF viewer.\n\nThere is a choice of two storage backends depending on requirements:\n\n#### git\n\nDesigned to be compatible with the Git protocol. This means annotations can be added or edited using standard git flow mechanisms such as a pull request and all new content can go through a review process before going public. \n\n#### pack\n\nDesigned to be highly-scalable and disk efficient. This backend uses technology that is part of the distributed ledger used within the [Tezos blockchain](https://tezos.com/).\n\n### Getting started\n\nMiiify can be run with Docker using either the git or pack backend. The example below uses the pack backend.\n\n#### Starting server\n\n```bash\ndocker compose pull pack\ndocker compose up pack -d\n```\n\n#### Check the server is running\n\n```bash\nhttp :\n```\n\n#### Stopping server\n```bash\ndocker compose down pack\n```\n\n### Basic concepts\n\nAnnotations are organised into containers and can be retrieved in pages to display within IIIF viewers such as [Mirador](https://projectmirador.org/). To filter the annotation page to a specific IIIF canvas an additional target parameter can be supplied. The examples below use [httpie](https://httpie.io/) with a live demo server which spins down when inactive.\n\nCreate an annotation container called my-container:\n```bash\nhttps miiify.onrender.com/annotations/ \u003c miiify/test/container1.json Slug:my-container\n```\n\nAdd an annotation called foobar to my-container:\n```bash\nhttps miiify.onrender.com/annotations/my-container/ \u003c miiify/test/annotation1.json Slug:foobar\n```\n\nAdd another annotation but use a system generated id:\n```bash\nhttps miiify.onrender.com/annotations/my-container/ \u003c miiify/test/annotation1.json\n```\n\nRetrieve the first annotation page from my-container:\n```bash\nhttps miiify.onrender.com/annotations/my-container/\\?page\\=0\n```\nproduces:\n```json\n{\n    \"@context\": \"http://iiif.io/api/presentation/3/context.json\",\n    \"id\": \"https://miiify.onrender.com/annotations/my-container/?page=0\",\n    \"items\": [\n        {\n            \"@context\": \"http://www.w3.org/ns/anno.jsonld\",\n            \"body\": \"http://example.org/post1\",\n            \"created\": \"2023-12-07T17:13:18Z\",\n            \"id\": \"https://miiify.onrender.com/annotations/my-container/4acb2493-96b2-4efb-a5aa-044cde1408f0\",\n            \"target\": \"http://example.com/page1\",\n            \"type\": \"Annotation\"\n        },\n        {\n            \"@context\": \"http://www.w3.org/ns/anno.jsonld\",\n            \"body\": \"http://example.org/post1\",\n            \"created\": \"2023-12-07T17:11:44Z\",\n            \"id\": \"https://miiify.onrender.com/annotations/my-container/foobar\",\n            \"target\": \"http://example.com/page1\",\n            \"type\": \"Annotation\"\n        }\n    ],\n    \"partOf\": {\n        \"created\": \"2023-12-07T17:10:20Z\",\n        \"id\": \"https://miiify.onrender.com/annotations/my-container/\",\n        \"label\": \"A Container for Web Annotations\",\n        \"total\": 2,\n        \"type\": \"AnnotationCollection\"\n    },\n    \"startIndex\": 0,\n    \"type\": \"AnnotationPage\"\n}\n```\n\nRetrieve the first annotation page from my-container but filter annotations based on their target:\n```bash\nhttps miiify.onrender.com/annotations/my-container/ \u003c miiify/test/annotation3.json\nhttps miiify.onrender.com/annotations/my-container/\\?page\\=0\\\u0026target\\=http://example.com/page3\n```\nproduces:\n```json\n{\n    \"@context\": \"http://iiif.io/api/presentation/3/context.json\",\n    \"id\": \"https://miiify.onrender.com/annotations/my-container/?page=0\u0026target=http://example.com/page3\",\n    \"items\": [\n        {\n            \"@context\": \"http://www.w3.org/ns/anno.jsonld\",\n            \"body\": \"http://example.org/post3\",\n            \"created\": \"2023-12-07T17:15:47Z\",\n            \"id\": \"https://miiify.onrender.com/annotations/my-container/20375636-3af4-44e4-b005-b5c5e625ec85\",\n            \"target\": \"http://example.com/page3\",\n            \"type\": \"Annotation\"\n        }\n    ],\n    \"partOf\": {\n        \"created\": \"2023-12-07T17:10:20Z\",\n        \"id\": \"https://miiify.onrender.com/annotations/my-container/\",\n        \"label\": \"A Container for Web Annotations\",\n        \"total\": 3,\n        \"type\": \"AnnotationCollection\"\n    },\n    \"startIndex\": 0,\n    \"type\": \"AnnotationPage\"\n}\n```\n\nRetrieve a single annotation:\n```bash\nhttps miiify.onrender.com/annotations/my-container/foobar\n```\nproduces\n```json\n{\n    \"@context\": \"http://www.w3.org/ns/anno.jsonld\",\n    \"body\": \"http://example.org/post1\",\n    \"created\": \"2023-12-07T17:11:44Z\",\n    \"id\": \"https://miiify.onrender.com/annotations/my-container/foobar\",\n    \"target\": \"http://example.com/page1\",\n    \"type\": \"Annotation\"\n}\n```\n\n### Tutorial\n\nSimple [video tutorial](https://miiifystore.s3.eu-west-2.amazonaws.com/presentations/simple-external-annotation.mp4) to show how to create annotations and display them in the Mirador IIIF viewer.\n\n### Other key features\n\n* Support for validating annotations using [ATD](https://atd.readthedocs.io/en/latest/atd-language.html#introduction) with a detailed example available [here](https://raw.githubusercontent.com/jptmoore/maniiifest/main/src/specification.atd)\n* Easy to use with Docker and Kubernetes\n* Support for ETag caching and collision avoidance\n* Simple key/value interface for working with IIIF manifests\n\n### Building from source\n\nTo build your own native Docker images:\n```\ncd miiify/test\n./build.sh pack\n```\n\n### Documentation\n\n[API specification](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/nationalarchives/miiify/main/doc/swagger.yml)\n\n\n\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnationalarchives%2Fmiiify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnationalarchives%2Fmiiify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnationalarchives%2Fmiiify/lists"}