Instance Storage version v11.0

Query Parameters

• totalRecords: (string - default: auto - pattern: exact|estimated|none|auto)

  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

• offset: (integer - default: 0 - minimum: 0 - maximum: 2147483647)

  Skip over a number of elements by specifying an offset value for the query

  Example:

  0

• limit: (integer - default: 10 - minimum: 0 - maximum: 2147483647)

  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

• query: (string)

  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.

  by parent ID or by child ID (using CQL)

  Example:

  (username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode
  
  subInstanceId==83a50dc6-b887-43d9-93ee-28b2c4cd11f8 superInstanceId==30fcc8e7-a019-43f4-b642-2edc389f4501 instanceRelationshipTypeId==758f13db-ffb4-440e-bb10-8a364aa6cb4a AND superInstanceId=30fcc8e7-a019-43f4-b642-2edc389f4501
  

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A relationship of a given type between a super-instance and a sub-instance",
  "javaType": "org.folio.rest.jaxrs.model.InstanceRelationship",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "superInstanceId": {
      "description": "ID (a UUID) of the super-instance. References an Instance record",
      "type": "string"
    },
    "subInstanceId": {
      "description": "ID (a UUID) of the sub-instance. References an Instance record",
      "type": "string"
    },
    "instanceRelationshipTypeId": {
      "description": "ID (a UUID) of the InstanceRelationshipType. References controlled vocabulary InstanceRelationshipTypes. Indicates the type of relationship between two Instance records.",
      "type": "string"
    },
    "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"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "superInstanceId",
    "subInstanceId",
    "instanceRelationshipTypeId"
  ]
}

Example:

{
  "id": "4b8093b8-8de9-41be-ad9a-0fbccb99052b",
  "superInstanceId": "601a8dc4-dee7-48eb-b03f-d02fdf0debd0",
  "subInstanceId": "83a50dc6-b887-43d9-93ee-28b2c4cd11f8",
  "instanceRelationshipTypeId": "758f13db-ffb4-440e-bb10-8a364aa6cb4a"
}

URI Parameters

• relationshipId: required(string)

URI Parameters

• relationshipId: required(string)

URI Parameters

• relationshipId: required(string)

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A relationship of a given type between a super-instance and a sub-instance",
  "javaType": "org.folio.rest.jaxrs.model.InstanceRelationship",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "superInstanceId": {
      "description": "ID (a UUID) of the super-instance. References an Instance record",
      "type": "string"
    },
    "subInstanceId": {
      "description": "ID (a UUID) of the sub-instance. References an Instance record",
      "type": "string"
    },
    "instanceRelationshipTypeId": {
      "description": "ID (a UUID) of the InstanceRelationshipType. References controlled vocabulary InstanceRelationshipTypes. Indicates the type of relationship between two Instance records.",
      "type": "string"
    },
    "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"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "superInstanceId",
    "subInstanceId",
    "instanceRelationshipTypeId"
  ]
}

Example:

{
  "id": "4b8093b8-8de9-41be-ad9a-0fbccb99052b",
  "superInstanceId": "601a8dc4-dee7-48eb-b03f-d02fdf0debd0",
  "subInstanceId": "83a50dc6-b887-43d9-93ee-28b2c4cd11f8",
  "instanceRelationshipTypeId": "758f13db-ffb4-440e-bb10-8a364aa6cb4a"
}

Query Parameters

• totalRecords: (string - default: auto - pattern: exact|estimated|none|auto)

  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

• offset: (integer - default: 0 - minimum: 0 - maximum: 2147483647)

  Skip over a number of elements by specifying an offset value for the query

  Example:

  0

• limit: (integer - default: 10 - minimum: 0 - maximum: 2147483647)

  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

• query: (string)

  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.

  by title (using CQL)

  Example:

  (username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode
  
  title="*uproot*"
  

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An instance record",
  "javaType": "org.folio.rest.jaxrs.model.Instance",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the instance record; a UUID",
      "$ref": "../common/uuid.json"
    },
    "_version": {
      "type": "integer",
      "description": "Record version for optimistic locking"
    },
    "hrid": {
      "type": "string",
      "description": "The human readable ID, also called eye readable ID. A system-assigned sequential ID which maps to the Instance ID"
    },
    "matchKey": {
      "type": "string",
      "description": "A unique instance identifier matching a client-side bibliographic record identification scheme, in particular for a scenario where multiple separate catalogs with no shared record identifiers contribute to the same Instance in Inventory. A match key is typically generated from select, normalized pieces of metadata in bibliographic records"
    },
    "sourceUri": {
      "type": "string",
      "description": "A remote URI uniquely identifying the source of the instance"
    },
    "source": {
      "type": "string",
      "description": "The metadata source and its format of the underlying record to the instance record. (e.g. FOLIO if it's a record created in Inventory; MARC if it's a MARC record created in MARCcat or EPKB if it's a record coming from eHoldings; CONSORTIUM-MARC or CONSORTIUM-FOLIO for sharing Instances)."
    },
    "title": {
      "type": "string",
      "description": "The primary title (or label) associated with the resource"
    },
    "indexTitle": {
      "type": "string",
      "description": "Title normalized for browsing and searching; based on the title with articles removed"
    },
    "alternativeTitles": {
      "type": "array",
      "description": "List of alternative titles for the resource (e.g. original language version title of a movie)",
      "items": {
        "type": "object",
        "javaType": "org.folio.rest.jaxrs.model.AlternativeTitle",
        "properties": {
          "alternativeTitleTypeId": {
            "type": "string",
            "description": "UUID for an alternative title qualifier",
            "$ref": "../common/uuid.json"
          },
          "alternativeTitle": {
            "type": "string",
            "description": "An alternative title for the resource"
          },
          "authorityId": {
            "type": "string",
            "description": "UUID of authority record that controls an alternative title",
            "$ref": "../common/uuid.json"
          }
        }
      },
      "uniqueItems": true
    },
    "editions": {
      "type": "array",
      "description": "The edition statement, imprint and other publication source information",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "series": {
      "type": "array",
      "description": "List of series titles associated with the resource (e.g. Harry Potter)",
      "items": {
        "type": "object",
        "javaType": "org.folio.rest.jaxrs.model.SeriesItem",
        "properties": {
          "value": {
            "type": "string",
            "description": "Series title value"
          },
          "authorityId": {
            "type": "string",
            "description": "UUID of authority record that controls an series title",
            "$ref": "../common/uuid.json"
          }
        },
        "additionalProperties": false,
        "required": [
          "value"
        ]
      },
      "uniqueItems": true
    },
    "identifiers": {
      "type": "array",
      "description": "An extensible set of name-value pairs of identifiers associated with the resource",
      "minItems": 0,
      "items": {
        "type": "object",
        "$ref": "../common/identifier.json"
      }
    },
    "contributors": {
      "type": "array",
      "description": "List of contributors",
      "minItems": 0,
      "items": {
        "type": "object",
        "javaType": "org.folio.rest.jaxrs.model.Contributor",
        "properties": {
          "name": {
            "type": "string",
            "description": "Personal name, corporate name, meeting name"
          },
          "contributorTypeId": {
            "type": "string",
            "description": "UUID for the contributor type term defined in controlled vocabulary",
            "$ref": "../common/uuid.json"
          },
          "contributorTypeText": {
            "type": "string",
            "description": "Free text element for adding contributor type terms other that defined by the MARC code list for relators"
          },
          "contributorNameTypeId": {
            "type": "string",
            "description": "UUID of contributor name type term defined by the MARC code list for relators",
            "$ref": "../common/uuid.json"
          },
          "authorityId": {
            "type": "string",
            "description": "UUID of authority record that controls the contributor",
            "$ref": "../common/uuid.json"
          },
          "contributorNameType": {
            "type": "object",
            "description": "Dereferenced contributor-name type",
            "javaType": "org.folio.rest.jaxrs.model.ContributorNameTypeVirtual",
            "$ref": "contributornametype.json",
            "readonly": true,
            "folio:isVirtual": true,
            "folio:linkBase": "contributor-name-types",
            "folio:linkFromField": "contributorNameTypeId",
            "folio:linkToField": "id",
            "folio:includedElement": "contributorNameTypes.0"
          },
          "primary": {
            "type": "boolean",
            "description": "Whether this is the primary contributor"
          }
        },
        "additionalProperties": false,
        "required": [
          "name",
          "contributorNameTypeId"
        ]
      }
    },
    "subjects": {
      "type": "array",
      "description": "List of subject headings",
      "items": {
        "type": "object",
        "javaType": "org.folio.rest.jaxrs.model.Subject",
        "properties": {
          "value": {
            "type": "string",
            "description": "Subject heading value"
          },
          "authorityId": {
            "type": "string",
            "description": "UUID of authority record that controls a subject heading",
            "$ref": "../common/uuid.json"
          },
          "sourceId": {
            "type": "string",
            "description": "UUID of subject source",
            "$ref": "../common/uuid.json"
          },
          "typeId": {
            "type": "string",
            "description": "UUID of subject type",
            "$ref": "../common/uuid.json"
          }
        },
        "additionalProperties": false,
        "required": [
          "value"
        ]
      },
      "uniqueItems": true
    },
    "classifications": {
      "type": "array",
      "description": "List of classifications",
      "minItems": 0,
      "items": {
        "type": "object",
        "javaType": "org.folio.rest.jaxrs.model.Classification",
        "properties": {
          "classificationNumber": {
            "type": "string",
            "description": "Classification (e.g. classification scheme, classification schedule)"
          },
          "classificationTypeId": {
            "type": "string",
            "description": "UUID of classification schema (e.g. LC, Canadian Classification, NLM, National Agricultural Library, UDC, and Dewey)",
            "$ref": "../common/uuid.json"
          },
          "classificationType": {
            "type": "object",
            "description": "Dereferenced classification schema",
            "javaType": "org.folio.rest.jaxrs.model.ClassificationTypeVirtual",
            "$ref": "classificationtype.json",
            "readonly": true,
            "folio:isVirtual": true,
            "folio:linkBase": "classification-types",
            "folio:linkFromField": "classificationTypeId",
            "folio:linkToField": "id",
            "folio:includedElement": "classificationTypes.0"
          }
        },
        "additionalProperties": false,
        "required": [
          "classificationNumber",
          "classificationTypeId"
        ]
      }
    },
    "publication": {
      "type": "array",
      "description": "List of publication items",
      "items": {
        "type": "object",
        "javaType": "org.folio.rest.jaxrs.model.Publication",
        "properties": {
          "publisher": {
            "type": "string",
            "description": "Name of publisher, distributor, etc."
          },
          "place": {
            "type": "string",
            "description": "Place of publication, distribution, etc."
          },
          "dateOfPublication": {
            "type": "string",
            "description": "Date (year YYYY) of publication, distribution, etc."
          },
          "role": {
            "type": "string",
            "description": "The role of the publisher, distributor, etc."
          }
        }
      }
    },
    "publicationFrequency": {
      "type": "array",
      "description": "List of intervals at which a serial appears (e.g. daily, weekly, monthly, quarterly, etc.)",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "publicationRange": {
      "type": "array",
      "description": "The range of sequential designation/chronology of publication, or date range",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "electronicAccess": {
      "type": "array",
      "description": "List of electronic access items",
      "items": {
        "type": "object",
        "$ref": "../common/electronicAccessItem.json"
      }
    },
    "dates": {
      "type": "object",
      "description": "Instance Dates",
      "javaType": "org.folio.rest.jaxrs.model.InstanceDates",
      "properties": {
        "dateTypeId": {
          "type": "string",
          "description": "Date type ID",
          "$ref": "../common/uuid.json"
        },
        "date1": {
          "type": "string",
          "description": "Date 1",
          "maxLength": 4
        },
        "date2": {
          "type": "string",
          "description": "Date 2",
          "maxLength": 4
        }
      },
      "additionalProperties": false
    },
    "instanceTypeId": {
      "type": "string",
      "description": "UUID of the unique term for the resource type whether it's from the RDA content term list of locally defined",
      "$ref": "../common/uuid.json"
    },
    "instanceFormatIds": {
      "type": "array",
      "description": "UUIDs for the unique terms for the format whether it's from the RDA carrier term list of locally defined",
      "items": {
        "type": "string",
        "$ref": "../common/uuid.json"
      }
    },
    "instanceFormats": {
      "type": "array",
      "description": "List of dereferenced instance formats",
      "items": {
        "type": "object",
        "$ref": "../instance-formats/instanceformat.json"
      },
      "readonly": true,
      "folio:isVirtual": true,
      "folio:linkBase": "instance-formats",
      "folio:linkFromField": "instanceFormatIds",
      "folio:linkToField": "id",
      "folio:includedElement": "instanceFormats"
    },
    "physicalDescriptions": {
      "type": "array",
      "description": "Physical description of the described resource, including its extent, dimensions, and such other physical details as a description of any accompanying materials and unit type and size",
      "items": {
        "type": "string"
      }
    },
    "languages": {
      "type": "array",
      "description": "The set of languages used by the resource",
      "minItems": 0,
      "items": {
        "type": "string"
      }
    },
    "notes": {
      "type": "array",
      "description": "Bibliographic notes (e.g. general notes, specialized notes)",
      "items": {
        "type": "object",
        "javaType": "org.folio.rest.jaxrs.model.InstanceNote",
        "additionalProperties": false,
        "properties": {
          "instanceNoteTypeId": {
            "description": "ID of the type of note",
            "$ref": "../common/uuid.json"
          },
          "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
          }
        }
      }
    },
    "administrativeNotes": {
      "type": "array",
      "description": "Administrative notes",
      "minItems": 0,
      "items": {
        "type": "string"
      }
    },
    "modeOfIssuanceId": {
      "type": "string",
      "description": "UUID of the RDA mode of issuance, a categorization reflecting whether a resource is issued in one or more parts, the way it is updated, and whether its termination is predetermined or not (e.g. monograph,  sequential monograph, serial; integrating Resource, other)",
      "$ref": "../common/uuid.json"
    },
    "catalogedDate": {
      "type": "string",
      "description": "Date or timestamp on an instance for when is was considered cataloged"
    },
    "previouslyHeld": {
      "type": "boolean",
      "description": "Records the fact that the resource was previously held by the library for things like Hathi access, etc.",
      "default": false
    },
    "staffSuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed for others than catalogers"
    },
    "discoverySuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed in a discovery system",
      "default": false
    },
    "deleted": {
      "type": "boolean",
      "description": "Indicates whether the record was marked for deletion",
      "default": false
    },
    "statisticalCodeIds": {
      "type": "array",
      "description": "List of statistical code IDs",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "sourceRecordFormat": {
      "type": "string",
      "description": "Format of the instance source record, if a source record exists (e.g. FOLIO if it's a record created in Inventory,  MARC if it's a MARC record created in MARCcat or EPKB if it's a record coming from eHoldings)",
      "enum": [
        "MARC-JSON"
      ],
      "readonly": true
    },
    "statusId": {
      "type": "string",
      "description": "UUID for the Instance status term (e.g. cataloged, uncatalogued, batch loaded, temporary, other, not yet assigned)",
      "$ref": "../common/uuid.json"
    },
    "statusUpdatedDate": {
      "type": "string",
      "description": "Date [or timestamp] for when the instance status was updated"
    },
    "tags": {
      "description": "arbitrary tags associated with this instance",
      "id": "tags",
      "type": "object",
      "$ref": "../../raml-util/schemas/tags.schema"
    },
    "metadata": {
      "type": "object",
      "$ref": "../../raml-util/schemas/metadata.schema",
      "readonly": true
    },
    "holdingsRecords2": {
      "type": "array",
      "description": "List of holdings records",
      "items": {
        "type": "object",
        "$ref": "../holdings-storage/holdingsRecord.json"
      },
      "readonly": true,
      "folio:isVirtual": true,
      "folio:linkBase": "holdings-storage/holdings",
      "folio:linkFromField": "id",
      "folio:linkToField": "instanceId",
      "folio:includedElement": "holdingsRecords"
    },
    "natureOfContentTermIds": {
      "type": "array",
      "description": "Array of UUID for the Instance nature of content (e.g. bibliography, biography, exhibition catalogue, festschrift, newspaper, proceedings, research report, thesis or website)",
      "uniqueItems": true,
      "items": {
        "type": "string",
        "description": "Single UUID for the Instance nature of content",
        "$ref": "../common/uuid.json"
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "source",
    "title",
    "instanceTypeId"
  ]
}

Example:

{
  "id": "601a8dc4-dee7-48eb-b03f-d02fdf0debd0",
  "source": "Local: MARC",
  "title": "ADVANCING LIBRARY EDUCATION: TECHNOLOGICAL INNOVATION AND INSTRUCTIONAL DESIGN",
  "contributors": [
    {
      "name": "Sigal, Ari",
      "contributorNameTypeId": "2b94c631-fca9-4892-a730-03ee529ffe2a",
      "primary": true
    }
  ],
  "identifiers": [
    {
      "identifierTypeId": "2e48e713-17f3-4c13-a9f8-23845bb210af",
      "value": "9781466636897"
    },
    {
      "identifierTypeId": "6051f95c-028e-4c6a-8a9e-ee689dd51453",
      "value": "1"
    }
  ],
  "instanceTypeId": "2b94c631-fca9-4892-a730-03ee529ffe2c",
  "tags" : {
    "tagList" : [
      "important"
    ]
  }
}

Query Parameters

• query: (string)

  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 instances to delete, use cql.allRecords=1 to delete all. Deletes connected marc source records.

  Example:

  (username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode
  
  hrid=="in123-0*"
  

URI Parameters

• instanceId: required(string)

URI Parameters

• instanceId: required(string)

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An instance record patch request",
  "javaType": "org.folio.rest.jaxrs.model.InstancePatchRequest",
  "type": "object",
  "properties": {
    "id": {
      "description": "Unique identifier for the instance record",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "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}$"
    },
    "_version": {
      "description": "Version of the instance record",
      "type": "integer"
    }
  },
  "additionalProperties": true,
  "required": [
    "id",
    "_version"
  ]
}

Example:

{
  "id": "5480e6e5-05d9-4721-8b70-c1350f22219a",
  "_version": 2,
  "title": "Sample title"
}

URI Parameters

• instanceId: required(string)

URI Parameters

• instanceId: required(string)

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An instance record",
  "javaType": "org.folio.rest.jaxrs.model.Instance",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the instance record; a UUID",
      "$ref": "../common/uuid.json"
    },
    "_version": {
      "type": "integer",
      "description": "Record version for optimistic locking"
    },
    "hrid": {
      "type": "string",
      "description": "The human readable ID, also called eye readable ID. A system-assigned sequential ID which maps to the Instance ID"
    },
    "matchKey": {
      "type": "string",
      "description": "A unique instance identifier matching a client-side bibliographic record identification scheme, in particular for a scenario where multiple separate catalogs with no shared record identifiers contribute to the same Instance in Inventory. A match key is typically generated from select, normalized pieces of metadata in bibliographic records"
    },
    "sourceUri": {
      "type": "string",
      "description": "A remote URI uniquely identifying the source of the instance"
    },
    "source": {
      "type": "string",
      "description": "The metadata source and its format of the underlying record to the instance record. (e.g. FOLIO if it's a record created in Inventory; MARC if it's a MARC record created in MARCcat or EPKB if it's a record coming from eHoldings; CONSORTIUM-MARC or CONSORTIUM-FOLIO for sharing Instances)."
    },
    "title": {
      "type": "string",
      "description": "The primary title (or label) associated with the resource"
    },
    "indexTitle": {
      "type": "string",
      "description": "Title normalized for browsing and searching; based on the title with articles removed"
    },
    "alternativeTitles": {
      "type": "array",
      "description": "List of alternative titles for the resource (e.g. original language version title of a movie)",
      "items": {
        "type": "object",
        "javaType": "org.folio.rest.jaxrs.model.AlternativeTitle",
        "properties": {
          "alternativeTitleTypeId": {
            "type": "string",
            "description": "UUID for an alternative title qualifier",
            "$ref": "../common/uuid.json"
          },
          "alternativeTitle": {
            "type": "string",
            "description": "An alternative title for the resource"
          },
          "authorityId": {
            "type": "string",
            "description": "UUID of authority record that controls an alternative title",
            "$ref": "../common/uuid.json"
          }
        }
      },
      "uniqueItems": true
    },
    "editions": {
      "type": "array",
      "description": "The edition statement, imprint and other publication source information",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "series": {
      "type": "array",
      "description": "List of series titles associated with the resource (e.g. Harry Potter)",
      "items": {
        "type": "object",
        "javaType": "org.folio.rest.jaxrs.model.SeriesItem",
        "properties": {
          "value": {
            "type": "string",
            "description": "Series title value"
          },
          "authorityId": {
            "type": "string",
            "description": "UUID of authority record that controls an series title",
            "$ref": "../common/uuid.json"
          }
        },
        "additionalProperties": false,
        "required": [
          "value"
        ]
      },
      "uniqueItems": true
    },
    "identifiers": {
      "type": "array",
      "description": "An extensible set of name-value pairs of identifiers associated with the resource",
      "minItems": 0,
      "items": {
        "type": "object",
        "$ref": "../common/identifier.json"
      }
    },
    "contributors": {
      "type": "array",
      "description": "List of contributors",
      "minItems": 0,
      "items": {
        "type": "object",
        "javaType": "org.folio.rest.jaxrs.model.Contributor",
        "properties": {
          "name": {
            "type": "string",
            "description": "Personal name, corporate name, meeting name"
          },
          "contributorTypeId": {
            "type": "string",
            "description": "UUID for the contributor type term defined in controlled vocabulary",
            "$ref": "../common/uuid.json"
          },
          "contributorTypeText": {
            "type": "string",
            "description": "Free text element for adding contributor type terms other that defined by the MARC code list for relators"
          },
          "contributorNameTypeId": {
            "type": "string",
            "description": "UUID of contributor name type term defined by the MARC code list for relators",
            "$ref": "../common/uuid.json"
          },
          "authorityId": {
            "type": "string",
            "description": "UUID of authority record that controls the contributor",
            "$ref": "../common/uuid.json"
          },
          "contributorNameType": {
            "type": "object",
            "description": "Dereferenced contributor-name type",
            "javaType": "org.folio.rest.jaxrs.model.ContributorNameTypeVirtual",
            "$ref": "contributornametype.json",
            "readonly": true,
            "folio:isVirtual": true,
            "folio:linkBase": "contributor-name-types",
            "folio:linkFromField": "contributorNameTypeId",
            "folio:linkToField": "id",
            "folio:includedElement": "contributorNameTypes.0"
          },
          "primary": {
            "type": "boolean",
            "description": "Whether this is the primary contributor"
          }
        },
        "additionalProperties": false,
        "required": [
          "name",
          "contributorNameTypeId"
        ]
      }
    },
    "subjects": {
      "type": "array",
      "description": "List of subject headings",
      "items": {
        "type": "object",
        "javaType": "org.folio.rest.jaxrs.model.Subject",
        "properties": {
          "value": {
            "type": "string",
            "description": "Subject heading value"
          },
          "authorityId": {
            "type": "string",
            "description": "UUID of authority record that controls a subject heading",
            "$ref": "../common/uuid.json"
          },
          "sourceId": {
            "type": "string",
            "description": "UUID of subject source",
            "$ref": "../common/uuid.json"
          },
          "typeId": {
            "type": "string",
            "description": "UUID of subject type",
            "$ref": "../common/uuid.json"
          }
        },
        "additionalProperties": false,
        "required": [
          "value"
        ]
      },
      "uniqueItems": true
    },
    "classifications": {
      "type": "array",
      "description": "List of classifications",
      "minItems": 0,
      "items": {
        "type": "object",
        "javaType": "org.folio.rest.jaxrs.model.Classification",
        "properties": {
          "classificationNumber": {
            "type": "string",
            "description": "Classification (e.g. classification scheme, classification schedule)"
          },
          "classificationTypeId": {
            "type": "string",
            "description": "UUID of classification schema (e.g. LC, Canadian Classification, NLM, National Agricultural Library, UDC, and Dewey)",
            "$ref": "../common/uuid.json"
          },
          "classificationType": {
            "type": "object",
            "description": "Dereferenced classification schema",
            "javaType": "org.folio.rest.jaxrs.model.ClassificationTypeVirtual",
            "$ref": "classificationtype.json",
            "readonly": true,
            "folio:isVirtual": true,
            "folio:linkBase": "classification-types",
            "folio:linkFromField": "classificationTypeId",
            "folio:linkToField": "id",
            "folio:includedElement": "classificationTypes.0"
          }
        },
        "additionalProperties": false,
        "required": [
          "classificationNumber",
          "classificationTypeId"
        ]
      }
    },
    "publication": {
      "type": "array",
      "description": "List of publication items",
      "items": {
        "type": "object",
        "javaType": "org.folio.rest.jaxrs.model.Publication",
        "properties": {
          "publisher": {
            "type": "string",
            "description": "Name of publisher, distributor, etc."
          },
          "place": {
            "type": "string",
            "description": "Place of publication, distribution, etc."
          },
          "dateOfPublication": {
            "type": "string",
            "description": "Date (year YYYY) of publication, distribution, etc."
          },
          "role": {
            "type": "string",
            "description": "The role of the publisher, distributor, etc."
          }
        }
      }
    },
    "publicationFrequency": {
      "type": "array",
      "description": "List of intervals at which a serial appears (e.g. daily, weekly, monthly, quarterly, etc.)",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "publicationRange": {
      "type": "array",
      "description": "The range of sequential designation/chronology of publication, or date range",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "electronicAccess": {
      "type": "array",
      "description": "List of electronic access items",
      "items": {
        "type": "object",
        "$ref": "../common/electronicAccessItem.json"
      }
    },
    "dates": {
      "type": "object",
      "description": "Instance Dates",
      "javaType": "org.folio.rest.jaxrs.model.InstanceDates",
      "properties": {
        "dateTypeId": {
          "type": "string",
          "description": "Date type ID",
          "$ref": "../common/uuid.json"
        },
        "date1": {
          "type": "string",
          "description": "Date 1",
          "maxLength": 4
        },
        "date2": {
          "type": "string",
          "description": "Date 2",
          "maxLength": 4
        }
      },
      "additionalProperties": false
    },
    "instanceTypeId": {
      "type": "string",
      "description": "UUID of the unique term for the resource type whether it's from the RDA content term list of locally defined",
      "$ref": "../common/uuid.json"
    },
    "instanceFormatIds": {
      "type": "array",
      "description": "UUIDs for the unique terms for the format whether it's from the RDA carrier term list of locally defined",
      "items": {
        "type": "string",
        "$ref": "../common/uuid.json"
      }
    },
    "instanceFormats": {
      "type": "array",
      "description": "List of dereferenced instance formats",
      "items": {
        "type": "object",
        "$ref": "../instance-formats/instanceformat.json"
      },
      "readonly": true,
      "folio:isVirtual": true,
      "folio:linkBase": "instance-formats",
      "folio:linkFromField": "instanceFormatIds",
      "folio:linkToField": "id",
      "folio:includedElement": "instanceFormats"
    },
    "physicalDescriptions": {
      "type": "array",
      "description": "Physical description of the described resource, including its extent, dimensions, and such other physical details as a description of any accompanying materials and unit type and size",
      "items": {
        "type": "string"
      }
    },
    "languages": {
      "type": "array",
      "description": "The set of languages used by the resource",
      "minItems": 0,
      "items": {
        "type": "string"
      }
    },
    "notes": {
      "type": "array",
      "description": "Bibliographic notes (e.g. general notes, specialized notes)",
      "items": {
        "type": "object",
        "javaType": "org.folio.rest.jaxrs.model.InstanceNote",
        "additionalProperties": false,
        "properties": {
          "instanceNoteTypeId": {
            "description": "ID of the type of note",
            "$ref": "../common/uuid.json"
          },
          "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
          }
        }
      }
    },
    "administrativeNotes": {
      "type": "array",
      "description": "Administrative notes",
      "minItems": 0,
      "items": {
        "type": "string"
      }
    },
    "modeOfIssuanceId": {
      "type": "string",
      "description": "UUID of the RDA mode of issuance, a categorization reflecting whether a resource is issued in one or more parts, the way it is updated, and whether its termination is predetermined or not (e.g. monograph,  sequential monograph, serial; integrating Resource, other)",
      "$ref": "../common/uuid.json"
    },
    "catalogedDate": {
      "type": "string",
      "description": "Date or timestamp on an instance for when is was considered cataloged"
    },
    "previouslyHeld": {
      "type": "boolean",
      "description": "Records the fact that the resource was previously held by the library for things like Hathi access, etc.",
      "default": false
    },
    "staffSuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed for others than catalogers"
    },
    "discoverySuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed in a discovery system",
      "default": false
    },
    "deleted": {
      "type": "boolean",
      "description": "Indicates whether the record was marked for deletion",
      "default": false
    },
    "statisticalCodeIds": {
      "type": "array",
      "description": "List of statistical code IDs",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "sourceRecordFormat": {
      "type": "string",
      "description": "Format of the instance source record, if a source record exists (e.g. FOLIO if it's a record created in Inventory,  MARC if it's a MARC record created in MARCcat or EPKB if it's a record coming from eHoldings)",
      "enum": [
        "MARC-JSON"
      ],
      "readonly": true
    },
    "statusId": {
      "type": "string",
      "description": "UUID for the Instance status term (e.g. cataloged, uncatalogued, batch loaded, temporary, other, not yet assigned)",
      "$ref": "../common/uuid.json"
    },
    "statusUpdatedDate": {
      "type": "string",
      "description": "Date [or timestamp] for when the instance status was updated"
    },
    "tags": {
      "description": "arbitrary tags associated with this instance",
      "id": "tags",
      "type": "object",
      "$ref": "../../raml-util/schemas/tags.schema"
    },
    "metadata": {
      "type": "object",
      "$ref": "../../raml-util/schemas/metadata.schema",
      "readonly": true
    },
    "holdingsRecords2": {
      "type": "array",
      "description": "List of holdings records",
      "items": {
        "type": "object",
        "$ref": "../holdings-storage/holdingsRecord.json"
      },
      "readonly": true,
      "folio:isVirtual": true,
      "folio:linkBase": "holdings-storage/holdings",
      "folio:linkFromField": "id",
      "folio:linkToField": "instanceId",
      "folio:includedElement": "holdingsRecords"
    },
    "natureOfContentTermIds": {
      "type": "array",
      "description": "Array of UUID for the Instance nature of content (e.g. bibliography, biography, exhibition catalogue, festschrift, newspaper, proceedings, research report, thesis or website)",
      "uniqueItems": true,
      "items": {
        "type": "string",
        "description": "Single UUID for the Instance nature of content",
        "$ref": "../common/uuid.json"
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "source",
    "title",
    "instanceTypeId"
  ]
}

Example:

{
  "id": "601a8dc4-dee7-48eb-b03f-d02fdf0debd0",
  "source": "Local: MARC",
  "title": "ADVANCING LIBRARY EDUCATION: TECHNOLOGICAL INNOVATION AND INSTRUCTIONAL DESIGN",
  "contributors": [
    {
      "name": "Sigal, Ari",
      "contributorNameTypeId": "2b94c631-fca9-4892-a730-03ee529ffe2a",
      "primary": true
    }
  ],
  "identifiers": [
    {
      "identifierTypeId": "2e48e713-17f3-4c13-a9f8-23845bb210af",
      "value": "9781466636897"
    },
    {
      "identifierTypeId": "6051f95c-028e-4c6a-8a9e-ee689dd51453",
      "value": "1"
    }
  ],
  "instanceTypeId": "2b94c631-fca9-4892-a730-03ee529ffe2c",
  "tags" : {
    "tagList" : [
      "important"
    ]
  }
}

URI Parameters

• instanceId: required(string)

URI Parameters

• instanceId: required(string)

URI Parameters

• instanceId: required(string)

URI Parameters

• instanceId: required(string)

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "MARC record representation, compatible with MarcEdit's JSON export and import",
  "javaType": "org.folio.rest.jaxrs.model.MarcJson",
  "type": "object",
  "properties": {
    "id": {
      "description": "id (UUID) of this MARC record, equals to the id of the instance record",
      "type": "string"
    },
    "leader": {
      "description": "The first field of a MARC record. Fixed length (24 characters). Data elements that primarily provide information for the processing of the record.",
      "type": "string",
      "minLength": 24,
      "maxLength": 24
    },
    "fields": {
      "description": "The variable fields of a MARC record, each identified by a three-character numeric tag.",
      "type": "array",
      "minItems": 2
    }
  },
  "additionalProperties": false,
  "required": [
    "leader",
    "fields"
  ]
}

Example:

{
  "leader":"00452nam a2200169 ca4500",
  "fields":[
    {"001":"029857716"},
    {"003":"DE-601"},
    {"005":"20180511131518.0"},
    {"008":"900626m19799999xxk\\\\\\\\\\\\\\\\\\\\\\000\\0\\eng\\d"},
    {"035":{"ind1":"\\",
            "ind2":"\\",
            "subfields":[{"a":"(DE-599)GBV029857716"}]}},
    {"040":{"ind1":"\\",
            "ind2":"\\",
            "subfields":[{"b":"ger"},
                         {"c":"GBVCP"}]}},
    {"041":{"ind1":"0",
            "ind2":"\\",
            "subfields":[{"a":"eng"}]}},
    {"044":{"ind1":"\\",
            "ind2":"\\",
            "subfields":[{"a":"xxk"},
                         {"a":"at"}]}},
    {"100":{"ind1":"1",
            "ind2":"\\",
            "subfields":[{"a":"Adams, Douglas"}]}},
    {"245":{"ind1":"1",
            "ind2":"4",
            "subfields":[{"a":"The Hitch Hiker's guide to the Galaxy"},
                         {"c":"Douglas Adams"}]}},
    {"246":{"ind1":"1",
            "ind2":"3",
            "subfields":[{"i":"Nebent."},
                         {"a":"The hitchhiker series"}]}},
    {"264":{"ind1":"3",
            "ind2":"1",
            "subfields":[{"a":"London [u.a.]"},
                         {"b":"Pan Books"},
                         {"c":"1979-"}]}}
  ]
}

URI Parameters

• instanceId: required(string)

URI Parameters

• instanceId: required(string)

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "DTO for fetching records by POST request",
  "javaType": "org.folio.rest.jaxrs.model.RetrieveEntitiesRequest",
  "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\""
}