http://localhost
Storage for holdings in the inventory
Retrieve a list of holding items.
GET /holdings-storage/holdings
How to calculate the totalRecords property. "exact" for the correct number, "estimated" for an estimation, "auto" to automatically select "exact" or "estimated", "none" for suppressing the totalRecords property. For details see https://github.com/folio-org/raml-module-builder#estimated-totalrecords
Example:
none
Skip over a number of elements by specifying an offset value for the query
Example:
0
Limit the number of elements returned in the response. Using limit=0 will return totalRecords with the exact value. For details about totalRecords see https://github.com/folio-org/raml-module-builder#estimated-totalrecords
Example:
10
A query expressed as a CQL string (see dev.folio.org/reference/glossary#cql) using valid searchable fields. The first example below shows the general form of a full CQL query, but those fields might not be relevant in this context.
Sorting by a foreign table field is not supported; the only exception is a query of this form: 'instanceId=="
Example:
(username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode
instanceId=="2b94c631-fca9-4892-a730-03ee529ffe2a"
Returns a list of holding items
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A collection of holdings records",
"type": "object",
"properties": {
"holdingsRecords": {
"description": "List of holdings records",
"id": "holdingsRecord",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A holdings record",
"javaType": "org.folio.rest.jaxrs.model.HoldingsRecord",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "the unique ID of the holdings record; UUID",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"_version": {
"type": "integer",
"description": "Record version for optimistic locking"
},
"sourceId": {
"description": "(A reference to) the source of a holdings record",
"type": "string",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"hrid": {
"type": "string",
"description": "the human readable ID, also called eye readable ID. A system-assigned sequential ID which maps to the Instance ID"
},
"holdingsTypeId": {
"type": "string",
"description": "unique ID for the type of this holdings record, a UUID",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"formerIds": {
"type": "array",
"description": "Previous ID(s) assigned to the holdings record",
"items": {
"type": "string"
},
"uniqueItems": true
},
"instanceId": {
"description": "Inventory instances identifier",
"type": "string",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"permanentLocationId": {
"type": "string",
"description": "The permanent shelving location in which an item resides.",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"temporaryLocationId": {
"type": "string",
"description": "Temporary location is the temporary location, shelving location, or holding which is a physical place where items are stored, or an Online location.",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"effectiveLocationId": {
"type": "string",
"description": "Effective location is calculated by the system based on the values in the permanent and temporary locationId fields.",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"electronicAccess": {
"description": "List of electronic access items",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Electronic access item",
"javaType": "org.folio.rest.jaxrs.model.ElectronicAccessItem",
"additionalProperties": false,
"properties": {
"uri": {
"type": "string",
"description": "uniform resource identifier (URI) is a string of characters designed for unambiguous identification of resources"
},
"linkText": {
"type": "string",
"description": "the value of the MARC tag field 856 2nd indicator, where the values are: no information provided, resource, version of resource, related resource, no display constant generated"
},
"materialsSpecification": {
"type": "string",
"description": "materials specified is used to specify to what portion or aspect of the resource the electronic location and access information applies (e.g. a portion or subset of the item is electronic, or a related electronic resource is being linked to the record)"
},
"publicNote": {
"type": "string",
"description": "URL public note to be displayed in the discovery"
},
"relationshipId": {
"type": "string",
"description": "relationship between the electronic resource at the location identified and the item described in the record as a whole"
}
},
"required": [
"uri"
]
}
},
"additionalCallNumbers": {
"description": "Additional Call Numbers to track the history of identifiers assigned to an item.",
"type": "array",
"items": {
"type": "object",
"uniqueItems": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A call number",
"properties": {
"typeId": {
"type": "string",
"description": "unique ID for the type of call number on a holdings record, a UUID",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"prefix": {
"type": "string",
"description": "Prefix of the call number on the holding level."
},
"callNumber": {
"type": "string",
"description": "Call Number is an identifier assigned to an item, usually printed on a label attached to the item."
},
"suffix": {
"type": "string",
"description": "Suffix of the call number on the holding level."
}
},
"additionalProperties": false,
"required": [
"callNumber"
]
}
},
"callNumberTypeId": {
"type": "string",
"description": "unique ID for the type of call number on a holdings record, a UUID",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"callNumberPrefix": {
"type": "string",
"description": "Prefix of the call number on the holding level."
},
"callNumber": {
"type": "string",
"description": "Call Number is an identifier assigned to an item, usually printed on a label attached to the item."
},
"callNumberSuffix": {
"type": "string",
"description": "Suffix of the call number on the holding level."
},
"shelvingTitle": {
"type": "string",
"description": "Indicates the shelving form of title."
},
"acquisitionFormat": {
"type": "string",
"description": "Format of holdings record acquisition"
},
"acquisitionMethod": {
"type": "string",
"description": "Method of holdings record acquisition"
},
"receiptStatus": {
"type": "string",
"description": "Receipt status (e.g. pending, awaiting receipt, partially received, fully received, receipt not required, and cancelled)"
},
"administrativeNotes": {
"type": "array",
"description": "Administrative notes",
"minItems": 0,
"items": {
"type": "string"
}
},
"notes": {
"type": "array",
"description": "Notes about action, copy, binding etc.",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A holdings record note",
"javaType": "org.folio.rest.jaxrs.model.HoldingsNote",
"additionalProperties": false,
"properties": {
"holdingsNoteTypeId": {
"type": "string",
"description": "ID of the type of note",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"note": {
"type": "string",
"description": "Text content of the note"
},
"staffOnly": {
"type": "boolean",
"description": "If true, determines that the note should not be visible for others than staff",
"default": false
}
}
}
},
"illPolicyId": {
"type": "string",
"description": "unique ID for an ILL policy, a UUID",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"retentionPolicy": {
"type": "string",
"description": "Records information regarding how long we have agreed to keep something."
},
"digitizationPolicy": {
"description": "Records information regarding digitization aspects.",
"type": "string"
},
"holdingsStatements": {
"description": "Holdings record statements",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Holdings record statement",
"javaType": "org.folio.rest.jaxrs.model.HoldingsStatement",
"additionalProperties": false,
"properties": {
"statement": {
"type": "string",
"description": "Specifies the exact content to which the library has access, typically for continuing publications."
},
"note": {
"type": "string",
"description": "Note attached to a holdings statement"
},
"staffNote": {
"type": "string",
"description": "Private note attached to a holdings statement"
}
}
}
},
"holdingsStatementsForIndexes": {
"description": "Holdings record indexes statements",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Holdings record statement",
"javaType": "org.folio.rest.jaxrs.model.HoldingsStatement",
"additionalProperties": false,
"properties": {
"statement": {
"type": "string",
"description": "Specifies the exact content to which the library has access, typically for continuing publications."
},
"note": {
"type": "string",
"description": "Note attached to a holdings statement"
},
"staffNote": {
"type": "string",
"description": "Private note attached to a holdings statement"
}
}
}
},
"holdingsStatementsForSupplements": {
"description": "Holdings record supplements statements",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Holdings record statement",
"javaType": "org.folio.rest.jaxrs.model.HoldingsStatement",
"additionalProperties": false,
"properties": {
"statement": {
"type": "string",
"description": "Specifies the exact content to which the library has access, typically for continuing publications."
},
"note": {
"type": "string",
"description": "Note attached to a holdings statement"
},
"staffNote": {
"type": "string",
"description": "Private note attached to a holdings statement"
}
}
}
},
"copyNumber": {
"type": "string",
"description": "Item/Piece ID (usually barcode) for systems that do not use item records. Ability to designate the copy number if institution chooses to use copy numbers."
},
"numberOfItems": {
"type": "string",
"description": "Text (Number)"
},
"receivingHistory": {
"description": "Receiving history of holdings record",
"$schema": "http://json-schema.org/draft-04/schema#",
"javaType": "org.folio.rest.jaxrs.model.HoldingsReceivingHistory",
"additionalProperties": false,
"type": "object",
"properties": {
"displayType": {
"type": "string",
"description": "Display hint. 1: Display fields separately. 2: Display fields concatenated"
},
"entries": {
"type": "array",
"description": "Entries of receiving history",
"items": {
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Receiving history entry of holdings record",
"javaType": "org.folio.rest.jaxrs.model.HoldingsReceivingHistoryEntry",
"additionalProperties": false,
"type": "object",
"properties": {
"publicDisplay": {
"type": "boolean",
"description": "Defines if the receivingHistory should be visible to the public."
},
"enumeration": {
"type": "string",
"description": "This is the volume/issue number (e.g. v.71:no.6-2)"
},
"chronology": {
"type": "string",
"description": "Repeated element from Receiving history - Enumeration AND Receiving history - Chronology"
}
}
}
}
}
},
"discoverySuppress": {
"type": "boolean",
"description": "records the fact that the record should not be displayed in a discovery system"
},
"statisticalCodeIds": {
"type": "array",
"description": "List of statistical code IDs",
"items": {
"type": "string",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A universally unique identifier (UUID), this is a 128-bit number used to identify a record and is shown in hex with dashes, for example 6312d172-f0cf-40f6-b27d-9fa8feaf332f; the UUID version must be from 1-5; see https://dev.folio.org/guides/uuids/",
"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}$"
},
"uniqueItems": true
},
"tags": {
"description": "arbitrary tags associated with this holding",
"id": "tags",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "tags",
"properties": {
"tagList": {
"description": "List of tags",
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"metadata": {
"type": "object",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"required": [
"sourceId",
"instanceId",
"permanentLocationId"
]
}
},
"totalRecords": {
"description": "Estimated or exact total number of records",
"type": "integer"
},
"resultInfo": {
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "resultInfo.schema",
"description": "Faceting of result sets",
"type": "object",
"properties": {
"totalRecords": {
"type": "integer",
"description": "Estimated or exact total number of records. For details see https://github.com/folio-org/raml-module-builder#estimated-totalrecords"
},
"totalRecordsEstimated": {
"type": "boolean",
"description": "True if totalRecords is an estimation, false if it is the exact number"
},
"totalRecordsRounded": {
"type": "integer",
"description": "The rounded value of totalRecords if totalRecords is an estimation"
},
"responseTime": {
"type": "number",
"description": "Response time"
},
"facets": {
"type": "array",
"description": "Array of facets",
"items": {
"type": "object",
"description": "A facet",
"properties": {
"facetValues": {
"type": "array",
"description": "Array of facet values",
"items": {
"type": "object",
"description": "A facet value",
"properties": {
"count": {
"type": "integer",
"description": "Count of facet values"
},
"value": {
"description": "Value Object"
}
}
},
"additionalProperties": false
},
"type": {
"type": "string",
"description": "Type of facet"
}
},
"additionalProperties": false
}
},
"diagnostics": {
"type": "array",
"description": "Array of diagnostic information",
"items": {
"type": "object",
"description": "Diagnostic information",
"properties": {
"source": {
"type": "string",
"description": "Source reporting the diagnostic information"
},
"code": {
"type": "string",
"description": "Diagnostic Code"
},
"message": {
"type": "string",
"description": "Diagnostic Message"
},
"module": {
"type": "string",
"description": "Module reporting diagnostic information"
},
"recordCount": {
"type": "integer",
"description": "Record Count for diagnostics"
},
"query": {
"type": "string",
"description": "CQL Query associated with results"
}
}
}
}
},
"additionalProperties": false
}
},
"required": [
"holdingsRecords",
"totalRecords"
]
}
Example:
{
"holdingsRecords": [
{
"id": "65cb2bf0-d4c2-4886-8ad0-b76f1ba75d61",
"instanceId": "cd28da0f-a3e4-465c-82f1-acade4e8e170",
"sourceId": "8081d707-610f-4b50-a28b-c36a6d25191b",
"permanentLocationId": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"holdingsStatements": [
{
"statement": "Line 1",
"note": "Note to line 1"
},
{
"statement": "Line 2",
"note": "Note to line2"
}
],
"tags" : {
"tagList" : [
"important"
]
}
},
{
"id": "807084d2-1b6c-4448-a566-d3d9ebfd1c08",
"instanceId": "601a8dc4-dee7-48eb-b03f-d02fdf0debd0",
"sourceId": "a779e45e-0e5e-4303-9c93-09dbbd215134",
"permanentLocationId": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"holdingsStatements": [
{
"statement": "Line 1",
"note": "Note to line 1"
},
{
"statement": "Line 2",
"note": "Note to line2"
}
],"tags" : {
"tagList" : [
"important"
]
}
}
],
"totalRecords": 2
}
Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.
Media type: text/plain
Type: any
Example:
unable to list holdings -- malformed parameter 'query', syntax error at column 6
Not authorized to perform requested action
Media type: text/plain
Type: any
Example:
unable to list holdings -- unauthorized
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administrator
Create a new holding item.
POST /holdings-storage/holdings
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A holdings record",
"javaType": "org.folio.rest.jaxrs.model.HoldingsRecord",
"additionalProperties": false,
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the unique ID of the holdings record; UUID",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"_version": {
"type": "integer",
"description": "Record version for optimistic locking"
},
"sourceId": {
"description": "(A reference to) the source of a holdings record",
"type": "string",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"hrid": {
"type": "string",
"description": "the human readable ID, also called eye readable ID. A system-assigned sequential ID which maps to the Instance ID"
},
"holdingsTypeId": {
"type": "string",
"description": "unique ID for the type of this holdings record, a UUID",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"formerIds": {
"type": "array",
"description": "Previous ID(s) assigned to the holdings record",
"items": {
"type": "string"
},
"uniqueItems": true
},
"instanceId": {
"description": "Inventory instances identifier",
"type": "string",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"permanentLocationId": {
"type": "string",
"description": "The permanent shelving location in which an item resides.",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"temporaryLocationId": {
"type": "string",
"description": "Temporary location is the temporary location, shelving location, or holding which is a physical place where items are stored, or an Online location.",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"effectiveLocationId": {
"type": "string",
"description": "Effective location is calculated by the system based on the values in the permanent and temporary locationId fields.",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"electronicAccess": {
"description": "List of electronic access items",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Electronic access item",
"javaType": "org.folio.rest.jaxrs.model.ElectronicAccessItem",
"additionalProperties": false,
"properties": {
"uri": {
"type": "string",
"description": "uniform resource identifier (URI) is a string of characters designed for unambiguous identification of resources"
},
"linkText": {
"type": "string",
"description": "the value of the MARC tag field 856 2nd indicator, where the values are: no information provided, resource, version of resource, related resource, no display constant generated"
},
"materialsSpecification": {
"type": "string",
"description": "materials specified is used to specify to what portion or aspect of the resource the electronic location and access information applies (e.g. a portion or subset of the item is electronic, or a related electronic resource is being linked to the record)"
},
"publicNote": {
"type": "string",
"description": "URL public note to be displayed in the discovery"
},
"relationshipId": {
"type": "string",
"description": "relationship between the electronic resource at the location identified and the item described in the record as a whole"
}
},
"required": [
"uri"
]
}
},
"additionalCallNumbers": {
"description": "Additional Call Numbers to track the history of identifiers assigned to an item.",
"type": "array",
"items": {
"type": "object",
"uniqueItems": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A call number",
"properties": {
"typeId": {
"type": "string",
"description": "unique ID for the type of call number on a holdings record, a UUID",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"prefix": {
"type": "string",
"description": "Prefix of the call number on the holding level."
},
"callNumber": {
"type": "string",
"description": "Call Number is an identifier assigned to an item, usually printed on a label attached to the item."
},
"suffix": {
"type": "string",
"description": "Suffix of the call number on the holding level."
}
},
"additionalProperties": false,
"required": [
"callNumber"
]
}
},
"callNumberTypeId": {
"type": "string",
"description": "unique ID for the type of call number on a holdings record, a UUID",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"callNumberPrefix": {
"type": "string",
"description": "Prefix of the call number on the holding level."
},
"callNumber": {
"type": "string",
"description": "Call Number is an identifier assigned to an item, usually printed on a label attached to the item."
},
"callNumberSuffix": {
"type": "string",
"description": "Suffix of the call number on the holding level."
},
"shelvingTitle": {
"type": "string",
"description": "Indicates the shelving form of title."
},
"acquisitionFormat": {
"type": "string",
"description": "Format of holdings record acquisition"
},
"acquisitionMethod": {
"type": "string",
"description": "Method of holdings record acquisition"
},
"receiptStatus": {
"type": "string",
"description": "Receipt status (e.g. pending, awaiting receipt, partially received, fully received, receipt not required, and cancelled)"
},
"administrativeNotes": {
"type": "array",
"description": "Administrative notes",
"minItems": 0,
"items": {
"type": "string"
}
},
"notes": {
"type": "array",
"description": "Notes about action, copy, binding etc.",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A holdings record note",
"javaType": "org.folio.rest.jaxrs.model.HoldingsNote",
"additionalProperties": false,
"properties": {
"holdingsNoteTypeId": {
"type": "string",
"description": "ID of the type of note",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"note": {
"type": "string",
"description": "Text content of the note"
},
"staffOnly": {
"type": "boolean",
"description": "If true, determines that the note should not be visible for others than staff",
"default": false
}
}
}
},
"illPolicyId": {
"type": "string",
"description": "unique ID for an ILL policy, a UUID",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"retentionPolicy": {
"type": "string",
"description": "Records information regarding how long we have agreed to keep something."
},
"digitizationPolicy": {
"description": "Records information regarding digitization aspects.",
"type": "string"
},
"holdingsStatements": {
"description": "Holdings record statements",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Holdings record statement",
"javaType": "org.folio.rest.jaxrs.model.HoldingsStatement",
"additionalProperties": false,
"properties": {
"statement": {
"type": "string",
"description": "Specifies the exact content to which the library has access, typically for continuing publications."
},
"note": {
"type": "string",
"description": "Note attached to a holdings statement"
},
"staffNote": {
"type": "string",
"description": "Private note attached to a holdings statement"
}
}
}
},
"holdingsStatementsForIndexes": {
"description": "Holdings record indexes statements",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Holdings record statement",
"javaType": "org.folio.rest.jaxrs.model.HoldingsStatement",
"additionalProperties": false,
"properties": {
"statement": {
"type": "string",
"description": "Specifies the exact content to which the library has access, typically for continuing publications."
},
"note": {
"type": "string",
"description": "Note attached to a holdings statement"
},
"staffNote": {
"type": "string",
"description": "Private note attached to a holdings statement"
}
}
}
},
"holdingsStatementsForSupplements": {
"description": "Holdings record supplements statements",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Holdings record statement",
"javaType": "org.folio.rest.jaxrs.model.HoldingsStatement",
"additionalProperties": false,
"properties": {
"statement": {
"type": "string",
"description": "Specifies the exact content to which the library has access, typically for continuing publications."
},
"note": {
"type": "string",
"description": "Note attached to a holdings statement"
},
"staffNote": {
"type": "string",
"description": "Private note attached to a holdings statement"
}
}
}
},
"copyNumber": {
"type": "string",
"description": "Item/Piece ID (usually barcode) for systems that do not use item records. Ability to designate the copy number if institution chooses to use copy numbers."
},
"numberOfItems": {
"type": "string",
"description": "Text (Number)"
},
"receivingHistory": {
"description": "Receiving history of holdings record",
"$schema": "http://json-schema.org/draft-04/schema#",
"javaType": "org.folio.rest.jaxrs.model.HoldingsReceivingHistory",
"additionalProperties": false,
"type": "object",
"properties": {
"displayType": {
"type": "string",
"description": "Display hint. 1: Display fields separately. 2: Display fields concatenated"
},
"entries": {
"type": "array",
"description": "Entries of receiving history",
"items": {
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Receiving history entry of holdings record",
"javaType": "org.folio.rest.jaxrs.model.HoldingsReceivingHistoryEntry",
"additionalProperties": false,
"type": "object",
"properties": {
"publicDisplay": {
"type": "boolean",
"description": "Defines if the receivingHistory should be visible to the public."
},
"enumeration": {
"type": "string",
"description": "This is the volume/issue number (e.g. v.71:no.6-2)"
},
"chronology": {
"type": "string",
"description": "Repeated element from Receiving history - Enumeration AND Receiving history - Chronology"
}
}
}
}
}
},
"discoverySuppress": {
"type": "boolean",
"description": "records the fact that the record should not be displayed in a discovery system"
},
"statisticalCodeIds": {
"type": "array",
"description": "List of statistical code IDs",
"items": {
"type": "string",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A universally unique identifier (UUID), this is a 128-bit number used to identify a record and is shown in hex with dashes, for example 6312d172-f0cf-40f6-b27d-9fa8feaf332f; the UUID version must be from 1-5; see https://dev.folio.org/guides/uuids/",
"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}$"
},
"uniqueItems": true
},
"tags": {
"description": "arbitrary tags associated with this holding",
"id": "tags",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "tags",
"properties": {
"tagList": {
"description": "List of tags",
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"metadata": {
"type": "object",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"required": [
"sourceId",
"instanceId",
"permanentLocationId"
]
}
Example:
{
"id": "65cb2bf0-d4c2-4886-8ad0-b76f1ba75d61",
"instanceId": "cd28da0f-a3e4-465c-82f1-acade4e8e170",
"sourceId": "8081d707-610f-4b50-a28b-c36a6d25191b",
"permanentLocationId": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"holdingsStatements": [
{
"statement": "Line 1",
"note": "Note to line 1"
},
{
"statement": "Line 2",
"note": "Note to line2"
}
],
"tags" : {
"tagList" : [
"important"
]
}
}
Returns a newly created item, with server-controlled fields like 'id' populated
URI to the created holding item
Media type: application/json
Type: any
Example:
{
"id": "65cb2bf0-d4c2-4886-8ad0-b76f1ba75d61",
"instanceId": "cd28da0f-a3e4-465c-82f1-acade4e8e170",
"sourceId": "8081d707-610f-4b50-a28b-c36a6d25191b",
"permanentLocationId": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"holdingsStatements": [
{
"statement": "Line 1",
"note": "Note to line 1"
},
{
"statement": "Line 2",
"note": "Note to line2"
}
],
"tags" : {
"tagList" : [
"important"
]
}
}
Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.
Media type: text/plain
Type: any
Example:
"unable to add holding -- malformed JSON at 13:3"
Not authorized to perform requested action
Media type: text/plain
Type: any
Example:
unable to create holdings -- unauthorized
Validation errors
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "errors.schema",
"description": "A set of errors",
"type": "object",
"properties": {
"errors": {
"description": "List of errors",
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "error.schema",
"description": "An error",
"properties": {
"message": {
"type": "string",
"description": "Error message text"
},
"type": {
"type": "string",
"description": "Error message type"
},
"code": {
"type": "string",
"description": "Error message code"
},
"parameters": {
"description": "Error message parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "parameters.schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
},
"required": [
"message"
]
}
},
"total_records": {
"description": "Total number of errors",
"type": "integer"
}
}
}
Example:
{
"errors": [
{
"message": "may not be null",
"type": "1",
"code": "-1",
"parameters": [
{
"key": "moduleTo",
"value": "null"
}
]
}
]
}
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administrator
DELETE /holdings-storage/holdings
A query expressed as a CQL string (see dev.folio.org/reference/glossary#cql) using valid searchable fields. The first example below shows the general form of a full CQL query, but those fields might not be relevant in this context.
CQL to select holdings to delete, use cql.allRecords=1 to delete all
Example:
(username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode
callNumber=="123-0*"
Selected holdings deleted
Bad request, e.g. malformed query parameter
Media type: text/plain
Type: any
Example:
query parameter is empty
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administrator
Retrieve holding item with given {holdingId}
GET /holdings-storage/holdings/{holdingsRecordId}
Get Holdings Record by holdingsRecordId
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A holdings record",
"javaType": "org.folio.rest.jaxrs.model.HoldingsRecord",
"additionalProperties": false,
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the unique ID of the holdings record; UUID",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"_version": {
"type": "integer",
"description": "Record version for optimistic locking"
},
"sourceId": {
"description": "(A reference to) the source of a holdings record",
"type": "string",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"hrid": {
"type": "string",
"description": "the human readable ID, also called eye readable ID. A system-assigned sequential ID which maps to the Instance ID"
},
"holdingsTypeId": {
"type": "string",
"description": "unique ID for the type of this holdings record, a UUID",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"formerIds": {
"type": "array",
"description": "Previous ID(s) assigned to the holdings record",
"items": {
"type": "string"
},
"uniqueItems": true
},
"instanceId": {
"description": "Inventory instances identifier",
"type": "string",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"permanentLocationId": {
"type": "string",
"description": "The permanent shelving location in which an item resides.",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"temporaryLocationId": {
"type": "string",
"description": "Temporary location is the temporary location, shelving location, or holding which is a physical place where items are stored, or an Online location.",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"effectiveLocationId": {
"type": "string",
"description": "Effective location is calculated by the system based on the values in the permanent and temporary locationId fields.",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"electronicAccess": {
"description": "List of electronic access items",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Electronic access item",
"javaType": "org.folio.rest.jaxrs.model.ElectronicAccessItem",
"additionalProperties": false,
"properties": {
"uri": {
"type": "string",
"description": "uniform resource identifier (URI) is a string of characters designed for unambiguous identification of resources"
},
"linkText": {
"type": "string",
"description": "the value of the MARC tag field 856 2nd indicator, where the values are: no information provided, resource, version of resource, related resource, no display constant generated"
},
"materialsSpecification": {
"type": "string",
"description": "materials specified is used to specify to what portion or aspect of the resource the electronic location and access information applies (e.g. a portion or subset of the item is electronic, or a related electronic resource is being linked to the record)"
},
"publicNote": {
"type": "string",
"description": "URL public note to be displayed in the discovery"
},
"relationshipId": {
"type": "string",
"description": "relationship between the electronic resource at the location identified and the item described in the record as a whole"
}
},
"required": [
"uri"
]
}
},
"additionalCallNumbers": {
"description": "Additional Call Numbers to track the history of identifiers assigned to an item.",
"type": "array",
"items": {
"type": "object",
"uniqueItems": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A call number",
"properties": {
"typeId": {
"type": "string",
"description": "unique ID for the type of call number on a holdings record, a UUID",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"prefix": {
"type": "string",
"description": "Prefix of the call number on the holding level."
},
"callNumber": {
"type": "string",
"description": "Call Number is an identifier assigned to an item, usually printed on a label attached to the item."
},
"suffix": {
"type": "string",
"description": "Suffix of the call number on the holding level."
}
},
"additionalProperties": false,
"required": [
"callNumber"
]
}
},
"callNumberTypeId": {
"type": "string",
"description": "unique ID for the type of call number on a holdings record, a UUID",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"callNumberPrefix": {
"type": "string",
"description": "Prefix of the call number on the holding level."
},
"callNumber": {
"type": "string",
"description": "Call Number is an identifier assigned to an item, usually printed on a label attached to the item."
},
"callNumberSuffix": {
"type": "string",
"description": "Suffix of the call number on the holding level."
},
"shelvingTitle": {
"type": "string",
"description": "Indicates the shelving form of title."
},
"acquisitionFormat": {
"type": "string",
"description": "Format of holdings record acquisition"
},
"acquisitionMethod": {
"type": "string",
"description": "Method of holdings record acquisition"
},
"receiptStatus": {
"type": "string",
"description": "Receipt status (e.g. pending, awaiting receipt, partially received, fully received, receipt not required, and cancelled)"
},
"administrativeNotes": {
"type": "array",
"description": "Administrative notes",
"minItems": 0,
"items": {
"type": "string"
}
},
"notes": {
"type": "array",
"description": "Notes about action, copy, binding etc.",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A holdings record note",
"javaType": "org.folio.rest.jaxrs.model.HoldingsNote",
"additionalProperties": false,
"properties": {
"holdingsNoteTypeId": {
"type": "string",
"description": "ID of the type of note",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"note": {
"type": "string",
"description": "Text content of the note"
},
"staffOnly": {
"type": "boolean",
"description": "If true, determines that the note should not be visible for others than staff",
"default": false
}
}
}
},
"illPolicyId": {
"type": "string",
"description": "unique ID for an ILL policy, a UUID",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"retentionPolicy": {
"type": "string",
"description": "Records information regarding how long we have agreed to keep something."
},
"digitizationPolicy": {
"description": "Records information regarding digitization aspects.",
"type": "string"
},
"holdingsStatements": {
"description": "Holdings record statements",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Holdings record statement",
"javaType": "org.folio.rest.jaxrs.model.HoldingsStatement",
"additionalProperties": false,
"properties": {
"statement": {
"type": "string",
"description": "Specifies the exact content to which the library has access, typically for continuing publications."
},
"note": {
"type": "string",
"description": "Note attached to a holdings statement"
},
"staffNote": {
"type": "string",
"description": "Private note attached to a holdings statement"
}
}
}
},
"holdingsStatementsForIndexes": {
"description": "Holdings record indexes statements",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Holdings record statement",
"javaType": "org.folio.rest.jaxrs.model.HoldingsStatement",
"additionalProperties": false,
"properties": {
"statement": {
"type": "string",
"description": "Specifies the exact content to which the library has access, typically for continuing publications."
},
"note": {
"type": "string",
"description": "Note attached to a holdings statement"
},
"staffNote": {
"type": "string",
"description": "Private note attached to a holdings statement"
}
}
}
},
"holdingsStatementsForSupplements": {
"description": "Holdings record supplements statements",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Holdings record statement",
"javaType": "org.folio.rest.jaxrs.model.HoldingsStatement",
"additionalProperties": false,
"properties": {
"statement": {
"type": "string",
"description": "Specifies the exact content to which the library has access, typically for continuing publications."
},
"note": {
"type": "string",
"description": "Note attached to a holdings statement"
},
"staffNote": {
"type": "string",
"description": "Private note attached to a holdings statement"
}
}
}
},
"copyNumber": {
"type": "string",
"description": "Item/Piece ID (usually barcode) for systems that do not use item records. Ability to designate the copy number if institution chooses to use copy numbers."
},
"numberOfItems": {
"type": "string",
"description": "Text (Number)"
},
"receivingHistory": {
"description": "Receiving history of holdings record",
"$schema": "http://json-schema.org/draft-04/schema#",
"javaType": "org.folio.rest.jaxrs.model.HoldingsReceivingHistory",
"additionalProperties": false,
"type": "object",
"properties": {
"displayType": {
"type": "string",
"description": "Display hint. 1: Display fields separately. 2: Display fields concatenated"
},
"entries": {
"type": "array",
"description": "Entries of receiving history",
"items": {
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Receiving history entry of holdings record",
"javaType": "org.folio.rest.jaxrs.model.HoldingsReceivingHistoryEntry",
"additionalProperties": false,
"type": "object",
"properties": {
"publicDisplay": {
"type": "boolean",
"description": "Defines if the receivingHistory should be visible to the public."
},
"enumeration": {
"type": "string",
"description": "This is the volume/issue number (e.g. v.71:no.6-2)"
},
"chronology": {
"type": "string",
"description": "Repeated element from Receiving history - Enumeration AND Receiving history - Chronology"
}
}
}
}
}
},
"discoverySuppress": {
"type": "boolean",
"description": "records the fact that the record should not be displayed in a discovery system"
},
"statisticalCodeIds": {
"type": "array",
"description": "List of statistical code IDs",
"items": {
"type": "string",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A universally unique identifier (UUID), this is a 128-bit number used to identify a record and is shown in hex with dashes, for example 6312d172-f0cf-40f6-b27d-9fa8feaf332f; the UUID version must be from 1-5; see https://dev.folio.org/guides/uuids/",
"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}$"
},
"uniqueItems": true
},
"tags": {
"description": "arbitrary tags associated with this holding",
"id": "tags",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "tags",
"properties": {
"tagList": {
"description": "List of tags",
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"metadata": {
"type": "object",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"required": [
"sourceId",
"instanceId",
"permanentLocationId"
]
}
Example:
{
"id": "65cb2bf0-d4c2-4886-8ad0-b76f1ba75d61",
"instanceId": "cd28da0f-a3e4-465c-82f1-acade4e8e170",
"sourceId": "8081d707-610f-4b50-a28b-c36a6d25191b",
"permanentLocationId": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"holdingsStatements": [
{
"statement": "Line 1",
"note": "Note to line 1"
},
{
"statement": "Line 2",
"note": "Note to line2"
}
],
"tags" : {
"tagList" : [
"important"
]
}
}
Item with a given ID not found
Media type: text/plain
Type: any
Example:
"holding not found"
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administrator
Update holding item with given {holdingId}
PUT /holdings-storage/holdings/{holdingsRecordId}
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A holdings record",
"javaType": "org.folio.rest.jaxrs.model.HoldingsRecord",
"additionalProperties": false,
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the unique ID of the holdings record; UUID",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"_version": {
"type": "integer",
"description": "Record version for optimistic locking"
},
"sourceId": {
"description": "(A reference to) the source of a holdings record",
"type": "string",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"hrid": {
"type": "string",
"description": "the human readable ID, also called eye readable ID. A system-assigned sequential ID which maps to the Instance ID"
},
"holdingsTypeId": {
"type": "string",
"description": "unique ID for the type of this holdings record, a UUID",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"formerIds": {
"type": "array",
"description": "Previous ID(s) assigned to the holdings record",
"items": {
"type": "string"
},
"uniqueItems": true
},
"instanceId": {
"description": "Inventory instances identifier",
"type": "string",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"permanentLocationId": {
"type": "string",
"description": "The permanent shelving location in which an item resides.",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"temporaryLocationId": {
"type": "string",
"description": "Temporary location is the temporary location, shelving location, or holding which is a physical place where items are stored, or an Online location.",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"effectiveLocationId": {
"type": "string",
"description": "Effective location is calculated by the system based on the values in the permanent and temporary locationId fields.",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"electronicAccess": {
"description": "List of electronic access items",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Electronic access item",
"javaType": "org.folio.rest.jaxrs.model.ElectronicAccessItem",
"additionalProperties": false,
"properties": {
"uri": {
"type": "string",
"description": "uniform resource identifier (URI) is a string of characters designed for unambiguous identification of resources"
},
"linkText": {
"type": "string",
"description": "the value of the MARC tag field 856 2nd indicator, where the values are: no information provided, resource, version of resource, related resource, no display constant generated"
},
"materialsSpecification": {
"type": "string",
"description": "materials specified is used to specify to what portion or aspect of the resource the electronic location and access information applies (e.g. a portion or subset of the item is electronic, or a related electronic resource is being linked to the record)"
},
"publicNote": {
"type": "string",
"description": "URL public note to be displayed in the discovery"
},
"relationshipId": {
"type": "string",
"description": "relationship between the electronic resource at the location identified and the item described in the record as a whole"
}
},
"required": [
"uri"
]
}
},
"additionalCallNumbers": {
"description": "Additional Call Numbers to track the history of identifiers assigned to an item.",
"type": "array",
"items": {
"type": "object",
"uniqueItems": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A call number",
"properties": {
"typeId": {
"type": "string",
"description": "unique ID for the type of call number on a holdings record, a UUID",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"prefix": {
"type": "string",
"description": "Prefix of the call number on the holding level."
},
"callNumber": {
"type": "string",
"description": "Call Number is an identifier assigned to an item, usually printed on a label attached to the item."
},
"suffix": {
"type": "string",
"description": "Suffix of the call number on the holding level."
}
},
"additionalProperties": false,
"required": [
"callNumber"
]
}
},
"callNumberTypeId": {
"type": "string",
"description": "unique ID for the type of call number on a holdings record, a UUID",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"callNumberPrefix": {
"type": "string",
"description": "Prefix of the call number on the holding level."
},
"callNumber": {
"type": "string",
"description": "Call Number is an identifier assigned to an item, usually printed on a label attached to the item."
},
"callNumberSuffix": {
"type": "string",
"description": "Suffix of the call number on the holding level."
},
"shelvingTitle": {
"type": "string",
"description": "Indicates the shelving form of title."
},
"acquisitionFormat": {
"type": "string",
"description": "Format of holdings record acquisition"
},
"acquisitionMethod": {
"type": "string",
"description": "Method of holdings record acquisition"
},
"receiptStatus": {
"type": "string",
"description": "Receipt status (e.g. pending, awaiting receipt, partially received, fully received, receipt not required, and cancelled)"
},
"administrativeNotes": {
"type": "array",
"description": "Administrative notes",
"minItems": 0,
"items": {
"type": "string"
}
},
"notes": {
"type": "array",
"description": "Notes about action, copy, binding etc.",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A holdings record note",
"javaType": "org.folio.rest.jaxrs.model.HoldingsNote",
"additionalProperties": false,
"properties": {
"holdingsNoteTypeId": {
"type": "string",
"description": "ID of the type of note",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"note": {
"type": "string",
"description": "Text content of the note"
},
"staffOnly": {
"type": "boolean",
"description": "If true, determines that the note should not be visible for others than staff",
"default": false
}
}
}
},
"illPolicyId": {
"type": "string",
"description": "unique ID for an ILL policy, a UUID",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"retentionPolicy": {
"type": "string",
"description": "Records information regarding how long we have agreed to keep something."
},
"digitizationPolicy": {
"description": "Records information regarding digitization aspects.",
"type": "string"
},
"holdingsStatements": {
"description": "Holdings record statements",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Holdings record statement",
"javaType": "org.folio.rest.jaxrs.model.HoldingsStatement",
"additionalProperties": false,
"properties": {
"statement": {
"type": "string",
"description": "Specifies the exact content to which the library has access, typically for continuing publications."
},
"note": {
"type": "string",
"description": "Note attached to a holdings statement"
},
"staffNote": {
"type": "string",
"description": "Private note attached to a holdings statement"
}
}
}
},
"holdingsStatementsForIndexes": {
"description": "Holdings record indexes statements",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Holdings record statement",
"javaType": "org.folio.rest.jaxrs.model.HoldingsStatement",
"additionalProperties": false,
"properties": {
"statement": {
"type": "string",
"description": "Specifies the exact content to which the library has access, typically for continuing publications."
},
"note": {
"type": "string",
"description": "Note attached to a holdings statement"
},
"staffNote": {
"type": "string",
"description": "Private note attached to a holdings statement"
}
}
}
},
"holdingsStatementsForSupplements": {
"description": "Holdings record supplements statements",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Holdings record statement",
"javaType": "org.folio.rest.jaxrs.model.HoldingsStatement",
"additionalProperties": false,
"properties": {
"statement": {
"type": "string",
"description": "Specifies the exact content to which the library has access, typically for continuing publications."
},
"note": {
"type": "string",
"description": "Note attached to a holdings statement"
},
"staffNote": {
"type": "string",
"description": "Private note attached to a holdings statement"
}
}
}
},
"copyNumber": {
"type": "string",
"description": "Item/Piece ID (usually barcode) for systems that do not use item records. Ability to designate the copy number if institution chooses to use copy numbers."
},
"numberOfItems": {
"type": "string",
"description": "Text (Number)"
},
"receivingHistory": {
"description": "Receiving history of holdings record",
"$schema": "http://json-schema.org/draft-04/schema#",
"javaType": "org.folio.rest.jaxrs.model.HoldingsReceivingHistory",
"additionalProperties": false,
"type": "object",
"properties": {
"displayType": {
"type": "string",
"description": "Display hint. 1: Display fields separately. 2: Display fields concatenated"
},
"entries": {
"type": "array",
"description": "Entries of receiving history",
"items": {
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Receiving history entry of holdings record",
"javaType": "org.folio.rest.jaxrs.model.HoldingsReceivingHistoryEntry",
"additionalProperties": false,
"type": "object",
"properties": {
"publicDisplay": {
"type": "boolean",
"description": "Defines if the receivingHistory should be visible to the public."
},
"enumeration": {
"type": "string",
"description": "This is the volume/issue number (e.g. v.71:no.6-2)"
},
"chronology": {
"type": "string",
"description": "Repeated element from Receiving history - Enumeration AND Receiving history - Chronology"
}
}
}
}
}
},
"discoverySuppress": {
"type": "boolean",
"description": "records the fact that the record should not be displayed in a discovery system"
},
"statisticalCodeIds": {
"type": "array",
"description": "List of statistical code IDs",
"items": {
"type": "string",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A universally unique identifier (UUID), this is a 128-bit number used to identify a record and is shown in hex with dashes, for example 6312d172-f0cf-40f6-b27d-9fa8feaf332f; the UUID version must be from 1-5; see https://dev.folio.org/guides/uuids/",
"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}$"
},
"uniqueItems": true
},
"tags": {
"description": "arbitrary tags associated with this holding",
"id": "tags",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "tags",
"properties": {
"tagList": {
"description": "List of tags",
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"metadata": {
"type": "object",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"required": [
"sourceId",
"instanceId",
"permanentLocationId"
]
}
Example:
{
"id": "65cb2bf0-d4c2-4886-8ad0-b76f1ba75d61",
"instanceId": "cd28da0f-a3e4-465c-82f1-acade4e8e170",
"sourceId": "8081d707-610f-4b50-a28b-c36a6d25191b",
"permanentLocationId": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"holdingsStatements": [
{
"statement": "Line 1",
"note": "Note to line 1"
},
{
"statement": "Line 2",
"note": "Note to line2"
}
],
"tags" : {
"tagList" : [
"important"
]
}
}
Item successfully updated
Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.
Media type: text/plain
Type: any
Example:
"unable to update holding -- malformed JSON at 13:4"
Item with a given ID not found
Media type: text/plain
Type: any
Example:
"holding not found"
Optimistic locking version conflict
Media type: text/plain
Type: any
Example:
version conflict
Validation errors
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "errors.schema",
"description": "A set of errors",
"type": "object",
"properties": {
"errors": {
"description": "List of errors",
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "error.schema",
"description": "An error",
"properties": {
"message": {
"type": "string",
"description": "Error message text"
},
"type": {
"type": "string",
"description": "Error message type"
},
"code": {
"type": "string",
"description": "Error message code"
},
"parameters": {
"description": "Error message parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "parameters.schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
},
"required": [
"message"
]
}
},
"total_records": {
"description": "Total number of errors",
"type": "integer"
}
}
}
Example:
{
"errors": [
{
"message": "may not be null",
"type": "1",
"code": "-1",
"parameters": [
{
"key": "moduleTo",
"value": "null"
}
]
}
]
}
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administrator
Delete holding item with given {holdingId}
DELETE /holdings-storage/holdings/{holdingsRecordId}
Item deleted successfully
Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.
Media type: text/plain
Type: any
Example:
"unable to delete holding -- constraint violation"
Item with a given ID not found
Media type: text/plain
Type: any
Example:
"holding not found"
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administrator
Get Holdings by POST request
POST /holdings-storage/holdings/retrieve
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "DTO for fetching records by POST request",
"type": "object",
"properties": {
"offset": {
"description": "Skip over a number of elements by specifying an offset value for the query",
"type": "integer",
"minimum": 0,
"maximum": 2147483647,
"default": 0
},
"limit": {
"description": "Limit the number of elements returned in the response",
"type": "integer",
"minimum": 0,
"maximum": 2147483647,
"default": 10
},
"query": {
"description": "A query expressed as a CQL string",
"type": "string"
}
}
}
Example:
{
"limit": 10,
"offset": 10,
"query": "status=\"Available\""
}
Validation errors
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "errors.schema",
"description": "A set of errors",
"type": "object",
"properties": {
"errors": {
"description": "List of errors",
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "error.schema",
"description": "An error",
"properties": {
"message": {
"type": "string",
"description": "Error message text"
},
"type": {
"type": "string",
"description": "Error message type"
},
"code": {
"type": "string",
"description": "Error message code"
},
"parameters": {
"description": "Error message parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "parameters.schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
},
"required": [
"message"
]
}
},
"total_records": {
"description": "Total number of errors",
"type": "integer"
}
}
}
Example:
{
"errors": [
{
"message": "may not be null",
"type": "1",
"code": "-1",
"parameters": [
{
"key": "moduleTo",
"value": "null"
}
]
}
]
}