KeepRight

Integrating KeepRight

There are a few different ways to integrate KeepRight.

The first is to simply link to the declaration created on this site, using a URL like this: 

https://keepright.info/declaration/unique-declaration-id

You can also set the format of the declaration by sticking a /[format] onto the end of the URL.

API GET

The second way is via the API, which is a good way for systems to link to declarations. JSON is the default format; you can tag /txt, /json, /html, /md, /xml and /pdf onto the end to specify the format. 

GET https://api.keepright.info/declaration/unique-declaration-id
GET https://api.keepright.info/declaration/unique-declaration-id/txt
GET https://api.keepright.info/declaration/unique-declaration-id/pdf

Example: IIIF Integration #

If you publish a IIIF Presentation 3.0 manifest, you can link a KeepRight declaration from it using seeAlso. 

"seeAlso": [
  {
    "id": "https://api.keepright.info/declaration/unique-declaration-id/json",
    "type": "Dataset",
    "label": { "en": [ "KeepRight Declaration" ] },
    "format": "application/json",
    "profile": "https://raw.githubusercontent.com/Deep-Keep-Group/keepright-spec/main/schemas/keepright-declaration.0.1.0.schema.json"
  }
]
💻 💻 💻

Example: Dublin Core Integration #

If you publish Dublin Core metadata about an artwork, dataset, manuscript, image, catalogue record and so on, one way you could point from that metadata to a KeepRight declaration is to use dcterms:rights (or dc:rights in plain Dublin Core) for the human-readable declaration URL.

Also, and, where the format supports it, link the JSON declaration as a related machine-readable record using dcterms:hasFormat.

The examples below are a sensible starting point.

In an HTML page about the work, using the DC-HTML profile: 

<head profile="http://dublincore.org/specifications/dublin-core/dc-html/2008-08-04/">
  <link rel="schema.DCTERMS" href="http://purl.org/dc/terms/">

  <link rel="DCTERMS.rights"
        href="https://keepright.info/declaration/unique-declaration-id">

  <link rel="DCTERMS.hasFormat"
        title="KeepRight Declaration (JSON)"
        href="https://api.keepright.info/declaration/unique-declaration-id/json">
</head>

Or, if you'd rather, as a JSON-LD record, which mirrors the IIIF seeAlso pattern above and can carry format and conformsTo on the related KeepRight JSON: 

{
  "@context": {
    "dcterms": "http://purl.org/dc/terms/",
    "title": "dcterms:title",
    "rights":     { "@id": "dcterms:rights",     "@type": "@id" },
    "hasFormat":  { "@id": "dcterms:hasFormat",  "@type": "@id" },
    "format":     { "@id": "dcterms:format",     "@type": "@id" },
    "conformsTo": { "@id": "dcterms:conformsTo", "@type": "@id" }
  },
  "@id": "https://example.org/works/your-thing",
  "title": "Your Thing",
  "rights": "https://keepright.info/declaration/unique-declaration-id",
  "hasFormat": {
    "@id": "https://api.keepright.info/declaration/unique-declaration-id/json",
    "format": "https://www.iana.org/assignments/media-types/application/json",
    "conformsTo": "https://raw.githubusercontent.com/Deep-Keep-Group/keepright-spec/main/schemas/keepright-declaration.0.1.0.schema.json"
  }
}
💻 💻 💻

Example: BagIt Integration #

If you package material with BagIt, save a copy of the KeepRight JSON declaration inside the bag payload as data/metadata/keepright.json, then add a KeepRight-Declaration tag to bag-info.txt with the canonical declaration URL. 

bag-info.txt
  ...
  KeepRight-Declaration: https://keepright.info/declaration/unique-declaration-id

manifest-sha256.txt
  [generated hash]  data/metadata/keepright.json

data/
  metadata/
    keepright.json

Download the JSON from https://api.keepright.info/declaration/unique-declaration-id/json, add it to the bag, then re-run your bag tool's update or complete step so the new payload file is listed in the payload manifest. Validating the bag then checks that the snapshot is still present and unchanged. The JSON travels with the bag for offline preservation, while the KeepRight-Declaration tag advertises the live URL without opening the payload.

API POST

Tools and code may prefer to use a POST operation, we've got you covered for that too. The format is optional and defaults to json. 

POST https://api.keepright.info/declaration/lookup
Content-Type: application/json

{
  "id": "unique-declaration-id",
  "format": "json"
}

Status codes

API error responses are JSON. Rate limits 'cause it's a bot hellscape out there.

Creating your own declaration maker

You don't have to use keepright.info as the single source of declarations. You can write your own either as a webapp, local tool (like ours), or integrating with your DAM or CMS. There's more There will be more on how to do that over on the specification page. Or, if you're feeling awesome you could dive right in with the spec and schema over here: Deep-Keep-Group/keepright-spec.