Proposal for RTAC-2

As already mentioned, I assume that having a new goal might be more effective than patching RTAC.

One approach could be to expose all relevant Information in the response. In other words, RTAC-2 should just provide all (non classified) attributes of 'holding', 'item', and 'location'. This will allow a library to use all attributes of this objects to pass hints to a discovery system. (e.g. the note fields). The current RTAC provides only a selection of all possible information, which leads into the well documented limitations.

Request

Task	Method	Path	PostParms
Inquirer information about one instance defined by UUID	GET	/rtac/uuid/{instance_uuid}
Inquirer information about one instance defined by HRID	GET	/rtac/hrid/{instance_uuid}
Inquirer information about multiple instances defined by UUID (needs additional level in the schema of the response)	POST	/rtac/uuid	List of UUIDs
Inquirer information about multiple instances defined by HRID (needs additional level in the schema of the response)	POST	/rtac/hrid	List of HRIDs

Notes:

HRID as query parameter is indispensable for most German libraries.
Since clients are capable to do asynchronous concurrent requests, it seems be outdated to provide a batch mode (POST endpoints).

Response

According to current design patterns JSON is assumed as transport format for the RTAC response.

Example

Short hypothetical response to http://somehost/rtac/hrid/12345678

{
  "id" : "12345678",
  "holdings": [
    {
      "id": "28ead097-5e3d-44fe-b647-ec982a1e4433",
      "hrid": "a",
      "type": "electronic",
      "suppressDiscovery": false,
      "somethingUnknown": "Newly introduced attribute in the holding record",
      "items": [
        {
          "id": "28ead097-5e3d-44fe-b647-ec982a1e4413",
          "hrid": "1",
          "callNumber": "29K 216,2.Aufl.",
          "status": "available",
          "permanentLoanType": "lendable",
          "location": {
            "id": "Lehrbuchsammlung_3",
            "displayName": "Main building",
            "type": "Freihand",
            "somethingUnknown": "Newly introduced attribute in the location record"
          },
          "somethingUnknown": "Newly introduced attribute in the item record"
        }
      ]
    }
  ]
}

Preliminary definition the response. This version is far from complete. In the final version it should be capable to transport all attributes of 'holding', 'item' and 'location'.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "RTAC Holding Schema",
  "description": "Real Time Availability Check (RTAC) holding details.",
  "type": "object",
  "required": [
    "id",
    "holdings"
  ],
  "properties": {
    "id": {
      "description": "Id of the requested instance ('uuid' |'hrid')",
      "type": "string"
    },
    "holdings": {
      "type": "array",
      "description": "List of holdings",
      "holding": [
        {
          "$ref": "/schemas/rtac/holding"
        }
      ]
    }
  },

  "$defs": {
    "holding": {
      "$id": "/schemas/rtac/holding",
      "description": "holding details. (https://wiki.folio.org/pages/viewpage.action?pageId=54888355)",
      "type": "object",
      "required": [
        "id"
      ],
      "properties": {
        "id": {
          "description": "Uniform id of this holding record",
          "$ref": "/schemas/rtac/uuid"
        },
        "hrid": {
          "description": "Human readable id of this holding record",
          "type": "string"
        },
        "type": {
          "description": "Material type of this expression",
          "type": "string"
        },
        "urls": {
          "description": "List of possible URLs",
          "$ref": "/schemas/rtac/urls"
        },
        "uri": {
          "description": "?",
          "type": "string"
        },
        "suppressDiscovery": {
          "description": "Additional flag for the visibility",
          "type": "boolean"
        },
        "location": {
          "description": "Default storage room",
          "$ref": "/schemas/rtac/location"
        }
      },
      "items": {
        "type": "array",
        "description": "List of items",
        "item": [
          {
            "$ref": "/schemas/rtac/item"
          }
        ]
      }
    },

    "item": {
      "$id": "/schemas/rtac/item",
      "description": "Description of one item. (https://wiki.folio.org/pages/viewpage.action?pageId=54888358)",
      "type": "object",
      "properties": {
        "id": {
          "description": "Uniform id of this item",
          "$ref": "/schemas/rtac/uuid"
        },
        "hrid": {
          "description": "Human readable id of this item",
          "type": "string"
        },
        "callNumber": {
          "description": "The main call number (aka. shelf mark) of this item",
          "type": "string"
        },
        "barcode": {
          "description": "The Barcode of this item",
          "type": "string"
        },
        "acquisitionNumber": {
          "description": "?",
          "type": "string"
        },
        "status": {
          "description": "The current availibility status of this item in the circulation system",
          "type": "string"
        },
        "dueDate": {
          "description": "Item record's due date field",
          "type": "string"
        },
        "permanentLoanType": {
          "description": "The general type of loan for this item",
          "type": "string"
        },
        "temporaryLoanType": {
          "description": "The general type of loan for this item",
          "type": "string"
        },
        "location": {
          "description": "The effective storage room for this item",
          "$ref": "/schemas/rtac/location"
        }
      },
      "required": [
        "id",
        "hrid",
        "indicator",
        "status"
      ]
    },

    "location": {
      "$id": "/schemas/rtac/location",
      "description": "Storarage location refered in 'item' and 'holding' ",
      "type": "object",
      "required": [
        "id",
        "displayName",
        "type"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "displayName": {
          "type": "string"
        },
        "type": {
          "type": "string"
        }
      }
    },

    "uuid": {
      "$id": "/schemas/rtac/uuid",
      "description": "uuid for FOLIO data objects",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
    },

    "urls": {
      "$id": "/schemas/rtac/urls",
      "description": "List of Urls",
      "type": "array",
      "minItems": 1,
      "url": {
        "type": "string"
      }
    }
  }
}