jangle.org

Explain responses are means to advertise the search attributes of a given entity. At their simplest, they provide enough information to create an OpenSearch Description Document, but they can also include the supported CQL indexes, relations and modifiers available for a search client to perform more sophisticated queries.

Example:
http://connector.jangle.org/resources/search/description/

Methods allowed: GET, HEAD

Content-type required: application/json

JSON Schema:

{
"description":"A Jangle Explain Response",
"type":"object",
"properties":{
  "type":{"type":"string","pattern":"/^explain$/"},
  "request":{"type":"string","format":"uri"},
  "shortname":{"type":"string","optional":true,"maxLength":16},
  "description":{"type":"string","maxLength":1024},
  "template":{"type":"string","format":"uri"},
  "contact":{"type":"string","format":"email","optional":true},
  "tags":{"type":"array","items":{"type":"string"},"optional":true},
  "longname":{"type":"string","optional":true,"maxLength":48},
  "image":{"type":"object","optional":true,"properties":{
    "height":{"type":"integer","minimum":0,"optional":true},
    "width":{"type":"integer","minimum":0,"optional":true},
    "type":{"type":"string","optional":true},
    "location":{"type":"string","format":"url"}}
  },
  "query":{"type":"object","optional":true,"properties":{
    "example":{"type":"string","optional":true},
    "context-sets",{"type":"array","items":{"type":"object","optional":true,"properties":{
      "identifier":{"type":"string","format":"uri"},
      "name":{"type":"string"},
      "indexes":{type":"array","items":{"type":"string"}}
      }
    }
  },
  "developer":{"type":"string","optional":true,"maxLength":64},
  "attribution":{"type":"string","optional":true,"maxLength":256},
  "syndicationright":{"type":"string","enum":
    ["open","limited","private","closed"],"optional":true},
  "adultcontent":{"type":"boolean","optional":true},
  "language":{"type":["string","array"],"items":{"type":"string"},"optional":true},
  "inputencoding":{"type":["string","array"],"items":{"type":"string"},"optional":true},
  "outputencoding":{"type":["string","array"],"items":{"type":"string"},"optional":true}
  }
}

An example JSON response:

{
    "type":"explain",
    "shortname":"Bibliographic records",
    "longname":"Search Bibliographic records in OpenBiblio",
    "request":"http:\/\/connector.jangle.org\/resources\/search\/description\/",
    "description":"Bibliographic records search.  Defaults to keyword anywhere.",
    "template":
      "http:\/\/connector.jangle.org\/resources\/search\/description\/?offset={startIndex?}&
count={count?}&query={searchTerms?}&format={jangle:format?}",
    "tags": ["catalog", "library"],
    "syndicationright":"open",
    "query":{
      "example":"dc.creator=thomas",
      "context-sets":[
        {
        "name":"dc",
        "identifier":"info:srw/cql-context-set/1/dc-v1.1",
        "indexes":["title","creator","subject","publisher","format","identifier"]
        },
        {
        "name":"rec",
        "identifier":"info:srw/cql-context-set/2/rec-1.1",
        "indexes":["identifier","collectionName","lastModificationDate","creationDate"]
        },
        {
        "name":"cql",
        "identifier":"info:srw/cql-context-set/1/cql-v1.2",
        "indexes":["allRecords","allIndexes","anyIndexes","keywords"]
        }
      ],
    },
  }
}

The definitions of each field are:

type:

Sets the type of the feed for the Jangle core to serialize properly. Must be explain

request:

The URI of the explain document.

shortname:

A brief label for the search. Optional. If not set, Jangle will use the entity name.

description:

A human readable description of the search target.

template:

A URL template conforming to OpenSearch URL parameters syntax.

contact:

An email address of the maintainer of the connector search. Optional

tags:

An optional array of terms to classify the search target.

longname:

An optional, human-readable string to identify the search target.

image:

An optional hash to provide an icon or image for the search target.
The elements of the hash are:

height:

The height, in pixels, of the image. Optional.

width:

The width, in pixels, of the image. Optional.

type:

The mime-type of the image. Optional.

location:

The URL of the image.

query:

A hash that sets the query definitions. Optional.
The elements of the hash are:

example:

An optional example query string that will return results for this search target.

context-sets:

An array of objects declaring the indexes available to search. Optional.
The elements of this object are:

name:

The prefix used in queries to declare the context set to use.

identifier:

The URI of the context set.

indexes:

An array of indexes available to use within the context set.

developer:

A human readable string of the maintainer or creator of the application. Optional

attribution:

An optional string containing any sources that should be credited for the content.

syndicationright:

An enumeration of redistribution privileges. Options are open, limited, private or closed. This element is optional (although omission defaults to "public".

adultcontent:

Boolean. Optional. Omission assumes "false".

language:

An optional string or array of language codes.

inputencoding:

Optional. Defines the character encoding of the query string. Default is UTF-8.

outputencoding:

Optional. Defines the character encoding of the query string. Default is UTF-8. Relevant for MARC-8 encoded data.