Extensions

SIP2 explicitly provides for extensions: Unknown field identifiers are to be skipped, not treated as an error. Everything described here rests on exactly that.

This profile follows three rules:

1. Every field of its own begins with X. SIP2 assigns no identifiers with that initial letter, so a collision with the protocol is ruled out – today and later.
2. No fixed field is altered. Length, order and meaning of the fields without identifier stay as SIP2 describes them. Touching them shifts the entire message for every foreign device.
3. Every field of its own is dispensable. A device that knows none of the extensions works fully – it receives less information, but never wrong information.

The extension fields#

XK and XL – type of identifier#

The SBC standard knows three identifiers side by side for an item: the barcode number, the accession number and – since RFID – the serial number of the transponder. The same applies to the patron card.

SIP2 has exactly one field for this: AB for the item, AA for the patron. Which of the three it holds cannot be seen from the message. As long as a library uses only one kind, a setting in the library system is enough. But as soon as a device works in mixed operation – barcode scanner and RFID reader – the approach fails: A twelve-digit transponder UID can be formally valid as a barcode number and then hits a different item.

XK and XL remove the guesswork. If the information is missing, the setting in the library system still applies – older devices run unchanged.

XP – PIN#

For checking, SIP2 knows only AD, the patron's password. In practice these are two different things: a password with which the patron signs in to the online catalogue, and a short PIN they enter on the numeric keypad of a unit.

Carrying both in the same field forces the library system into an either-or setting. With XP a library can offer both.

XZ – transaction number#

The transaction number is the key under which a checkout is held in the library system. A device does not need it to work – but anyone clarifying a disputed transaction finds it instantly. It therefore belongs on the receipt and in the device's log.

XH and XD – account information in brief#

Both could be derived from the item list – but a device would have to request and evaluate the complete list to do so. That is a lot of effort for two figures that appear on every account screen; on an account with sixty items it is noticeably much.

XW – fees not yet posted#

BV states an amount but not where it came from. Part of it may have arisen at this very moment – an item returned late, a fee for a renewal – and the library system keeps it separate until it is posted at the desk.

For the patron the difference matters: what has been owed for months is familiar; what has just been incurred has never been mentioned to them. Presented unexplained as a single sum, they will take it for an error.

The amount is given in cents and therefore without a separator – for BV a device has to cope with both point and comma, here there is nothing to confuse.

XV and XR – what can be renewed#

Whether a renewal succeeds depends on holds, the maximum number of renewals, the fee rate of the item and on how early the library allows renewal at all. None of this appears in the item list, and a device cannot work it out.

Without this information a self-checkout unit can only ever offer the button and display the refusal afterwards. That is the worst of all options: whoever reads "not possible" presses a second time.

XR repeats in the same order as AU and carries five details separated by tab characters (09):

XR1140360000123<TAB>N<TAB>The item is on hold for someone else.<TAB><TAB>|
XR1140360000131<TAB>J<TAB><TAB>22.09.2026<TAB>50|
                │   │   │      │           └─ fee in cents
                │   │   │      └───────────── new due date
                │   │   └──────────────────── reason, if it cannot be renewed
                │   └──────────────────────── `J` renewable, `N` not
                └──────────────────────────── item identifier

With N the last two details stay empty – there is neither a new due date nor a fee. With J they tell the patron in advance what they get and what it costs.

XR is only sent if the charged items were requested as well (position 2 of the summary). Items are matched by order; a device should nevertheless compare the identifier rather than rely on that alone.

XC – address template for cover images#

A self-checkout unit showing an account list shows lines of text. A cover image next to them answers "which book is that?" faster than any title – and someone who does not read the title still recognises it.

The images therefore do not travel through the protocol. A cover is easily 50 KB; base64-encoded that becomes 67 KB, and with ten loans half a megabyte would sit in a single message. SIP2 is line-oriented – such lines are no longer a protocol but a file transfer by the wrong means.

XC states the address instead. The device fills in two placeholders:

XChttp://{host}:8080/sip2/v1/cover?art=BAR&id={id}
        │                                      └─ item identifier, as it appears
        │                                         in AB, AU, AS or CD
        └───────────────────────────────────────── the address at which the
                                                   device currently reaches the
                                                   library system

Only the device can fill in {host}: it knows which address the connection was made on. A library system with two network cards would have to guess and would guess wrong. Everything else – including the type of item identifier – is already in the template; only the library system knows which identifier its lists carry.

The field appears in the system status and nowhere else: it applies to every list and every workflow, and a device asks for the system status before doing anything else anyway. Without XC the device shows no covers – and nothing else changes.

On the response:

• An existing cover is returned as an image (image/jpeg, image/png, image/gif).
• If there is none, 404 is the right answer. The device then hides the spot; a placeholder image would be worse, because it looks like a fault.
• A Cache-Control with a long lifetime belongs with it: covers hardly ever change, and the same list is reloaded often.

XE – character set#

SIP2 names code page 850 as its character set and adds that anything else must be "mutually defined" by device and library system – a way of doing so during operation is not part of the protocol. In practice this means two settings in two places, and woe betide if they disagree. Set wrongly, it shows up as mangled umlauts in titles and patron names.

XE turns this into a question and an answer. The device states what it can do in the system status, the library system answers with what applies. If the field is missing, Windows-1252 applies – which is why two systems that know nothing of it still understand each other.

Two provisions make UTF-8 safe in the first place, and both are set out in the message structure: Fixed fields stay ASCII, and the checksum runs over bytes. UTF-8 therefore changes nothing about the way of counting – an umlaut weighs two bytes there, and exactly those go into the sum.

XM – operating mode#

A library system in its daily closing is reachable but not ready for transactions. SIP2 has no value for this intermediate state: It can only be imitated by setting checkout and check-in to N individually – but then the device faces the same picture as with a library that offers no self-service at all.

XM tells the two apart. With MAINT the device knows it may ask again later and can tell the patron it will work again shortly.

XB – data set being served#

A library system often keeps several data sets side by side – branches, a neighbouring library taken over, a training set for courses. Which one it serves is a setting of the system, not of the device.

The library name in AM is not enough for this: Branches carry the same name of their parent body, and a training set is usually named exactly like the real one. Whoever stands at the unit and wants to know whether it looks at the right data sees the same text twice.

XB names the data set the way the library system itself names it – with BVS that is the name of the data directory:

XBdbf15|

The content is an identifier, not a caption: A device passes it on unchanged but does not interpret it. It belongs in the maintenance area of the device, not on the patron's screen.

If the field is missing, the device simply does not know – an older system does not send it, and nothing else changes.

XA – AFI values of the security#

With RFID the item carries its security itself: One byte on the tag, the AFI (Application Family Identifier), tells the gate at the exit whether to sound the alarm. Whoever circulates the item rewrites that byte – a self-service unit included.

In that case the library system does not track the security technology: "magnetic media" and "desensitize" of the checkout stand at U, and the device follows its own configuration. That is precisely where the trap lies. The same two values are then maintained in two places, and when they drift apart nobody notices: An item unsecured with the wrong value walks out unhindered; one secured with the wrong value sets off the alarm for the patron entitled to it. Both look like a fault of the technology rather than a misconfigured setting.

XA names both values, separated by a comma – the secured state first, the unsecured second:

XA0x07,0xC2|
  │    └──── unsecured: charged, the gate lets it pass
  └───────── secured: in the building, the gate sounds the alarm

They may be written in hexadecimal with a leading 0x or in decimal. The tools of the reader manufacturers show the values in hexadecimal, traces show them in decimal; the library system passes on whatever is configured in it and converts nothing. A device must be able to read both notations.

0x07 for secured and 0xC2 for unsecured are the customary values. They are not binding: What counts is solely what the gate in the building is set to. Hence a pair of values here and no fixed assignment – and hence the order within the field matters, not the value.

The field appears in the system status and nowhere else, for the same reason as XC: It applies to every transaction, and a device asks for the system status anyway before it does anything else. Without XA the device's own configuration remains in force – old devices and old library systems run unchanged.

XS, XU and XF – identification of the library system#

These three fields are attached to every response and tell the device whom it is talking to. That helps first of all with troubleshooting: The trace states which version answered. Beyond that, XU makes it possible to recognise a device that is too old before it sends messages the other side cannot understand.

XSbvssip/3.0.541|XUX3.0.400|XFcheckout,returns|

Checklist for manufacturers#

Anyone developing a device against this profile should work through these points:

• Does the sequence number of the response match the one sent? Responses with a differing number are to be discarded, not evaluated.
• Is the checksum verified and 97 sent on error?
• Are unknown field identifiers skipped rather than treated as an error?
• Is BX from the system status evaluated instead of sending unsupported commands on the off-chance?
• Is AF displayed unchanged instead of phrasing messages of one's own?
• On checkout, is the security deactivated only after a 1 in the result flag?
• Are the AFI values taken from XA instead of being maintained a second time in the device?
• Is the device's own clock set by the date/time sync from response 98?