BiblioShare Quick Start Guide

Welcome to BNC BiblioShare! This guide will help get you started.

Information on how to access data from BiblioShare can be found at booknetcanada.ca/bibliographic-data-distribution.


BiblioShare Basics

Deliver:

Deliver files to our FTP:

Ideally, the same file that is being supplied to a Canadian trade retailer, and at the same frequency.  At a minimum every record should have a cover image.

Both BNC Webform and BNC BiblioShare's Account Admin offer options to load files to BiblioShare but these actually move files to our FTP as described below.  In the case of Webform, image files are named appropriately with the product's ISBN as part of the service.  If you are submitting files using BiblioShare's Account Admin you should follow the naming conventions described below.

Process:

Files are automatically processed when delivered taking into consideration the options for naming and file type:

  • All files must be left in the appropriate sub-directory.  No files are automatically processed from the top directory.
  • All files must carry an appropriate extension for it's sub-directory if it is to process (detailed below), here's an overview:
    • "onix" sub-directory:  onix files carrying an .xml  extension
    • "image" sub-directory (and it's sub-directories: "interior" or "author"):  web enabled images – generally .jpg extension
    • 'sample" sub-directory: text based files as either .pdf or  EPUB files

The sub-sub-directories below "image" directory support simplified naming options giving you more flexibility (detailed below). 

The following is true for all 'image' and 'sample' files loaded to our FTP:

    • All files loaded MUST begin with a valid ISBN.  We prefer and recommend ISBN-13 but we will also accept ISBN-10. (Webform automatically provides this.)
    • We prefer and recommend ISBNs without dashes, but hyphens are ignored and if included. If the first 10 or 13 numbers are a valid ISBN-10 or 13 it can be processed.

See the heading FTP Structure below for a detailed explanation of our FTP site.

Zip Files:

Our automation will open zip files and process their contents.   Zip files are recommended for supplying multiple images files but are otherwise optional.   There's no recommendation on their naming convention other than uniquely named files that contain a company name are always recommended.

ONIX:

ONIX files are loaded to 'onix' sub-directory

  • All ONIX files must be loaded to the sub-directory 'onix' and carry an extension of .xml
  • Recommended naming: publishername_delta_yyyymmdd.xml
  • We automatically apply a unique name to every file for processing, but submitting files with identical names will affect our archiving and ability to troubleshoot problems.  We strongly recommend that all ONIX files arrive with a unique name.

BiblioShare archives the original ONIX files for several months and has special processing rules for archiving "FULL" and "DELTA" files.  

  • You should only supply a supply a file name with "_full_" in it if represents ALL records associated with this account
    • Submitting multiple files at the same time with "_full_" in them may result in processing problems. The last submitted file with "_full_" can bump the previous files out of the processing queue as it's assumed to represent all available records.
  • Submitting files with "_delta_" in the name shows that it is an update file.
  • Files with neither "_delta_" or "_full_" are assumed to be update files.

Images:

Images are loaded to 'image' directory

Image files are front cover images, back cover images, interiors spreads and author photos.   The image folder sub-directories 'interior', 'back' and 'author' allow looser naming conventions detailed below.

All files loaded to the 'image' directory or it's three sub-directories must be named by ISBN as detailed above and detailed in each section.   The following defines what can be processed in these directories.

  • JPG, TIF, PNG, and GIF formats are accepted
  • Image files must carry their extensions.
  • RGB colour space (No CMYK)
  • All files are converted and stored in the JPG format.
  • Our primary image is maintained in the same size as you provide
  • We want images up to 2500 pixels on the long side, but at a minimum they should be at least 500 pixels wide.
  • EDItEUR's current recommendation (based on retailer requests) is:
    • Short side:  Minimum 1000 pixels
    • Long side:  Maximum 2500 pixels

All images must start with a valid ISBN-13 or ISBN-10 as below in the file name in order to be processed.  Our processing will assume an image is a cover if it's not processed as an Interior or Author type as below.

If your file naming convention is ISBN based but does not follow the model described below, see the instructions for the sub-subdirectories \image\interior, \image\author & \image\back as they process any ISBN named files to the type of the directory name.  If you're still unsure or your automation can accommodate multiple directories, ask. 

Covers

All cover images must be named by a valid ISBN 10 or 13.

Example: 9781234567890.jpg

    • In general, you should be sending BiblioShare the same images you send to Amazon, Indigo, etc.
    • There is no need to submit thumbnails as we will create a standard one.

Back Cover

All back cover images must

  • start with a valid ISBN-13 or ISBN-10, 
  • follow that by the characters "back"
  • and can include other characters after, 

Example: 9781234567890_back.jpg


Using the image\back directory

Back cover images may be loaded to the sub-directory 'image\back'.  The same naming convention applies, except you do NOT need to use "back" in the file name as any ISBN based file loaded to the directory 'back' is assumed to be a back cover image.  

We do NOT currently offer access to this directory from the File Upload page in your BiblioShare.org admin account.

Clients using BooksoniX should NOT use the image\back directory as the processing detailed in Appendix 4 below applies only the "image" directory.

Interior images

All interior images must

    • start with a valid ISBN-13 or ISBN-10, 
    • follow that by the characters "in"
    • and can include other characters after, 
    • we will record a number at the end, and use it to identify a specific image.

The following image names are acceptable and would be considered identical in our processing. The first name on the list is our preference.

9781234567890_interior02.jpg
9781234567890.interior02.jpg
978-1-23456-7890IN2.jpg

Using the image\interior directory

Interior images may be loaded to the sub-directory 'image\interior'.  The same naming convention applies, except you do NOT need to use "in" or "interior" in the file name as any ISBN based file loaded to the directory 'interior' is assumed to be an interior.  Any additional number following the valid ISBN it is maintained to identify multiple interiors.  

We do NOT currently offer access to this directory from the File Upload page in your BiblioShare.org admin account.

Clients using BooksoniX should NOT use the image\interior directory as the processing detailed in Appendix 5 below applies only the "image" directory.

Author photos

All author images must

    • start with a valid ISBN-13 or ISBN-10, 
    • follow that by the characters "author"
    • can include other characters after, we assume these are an identification and preserve them but do not differentiate images based on them
    • we will record a number at the end, and use it to identify a specific image. If no number is provided we assume that the image number is "0".

The following image names are acceptable and would be considered identical in our processing.  The first name on the list is our preference.

9781234567890_author_Margaret_Atwood_01.jpg
9781234567890author1.jpg
978-1-23456-7890_author_Atwood1.jpg 

but these images would be considered different from above because the file ID has changed:

9781234567890_author_Margaret_Atwood.jpg  (we would process as author image "0")
9781234567890.author3.jpg

Using the image\author directory 

Author images may be loaded to the sub-directory 'image\author'.  The same naming convention applies, except you do NOT need to use "author" in the file name as any ISBN based file loaded to the directory 'author' is assumed to be an author photo.  Any additional text and final number following the valid ISBN it is maintained to identify multiple associated authors. 

We do NOT currently offer access to this directory from the File Upload page in your BiblioShare.org admin account.

Clients using BooksoniX should NOT use the image\interior directory as the processing detailed in Appendix 5 below applies only the "image" directory.

BooksoniX Clients

See Appendix 4  below for information on what BiblioShare will do with image feeds from BooksonIX.

Samples:

Samples as PDFs and EPUB files are loaded to the 'sample' sub-directory.  We accept several types

  • excerpt – also called sample chapters - a continuous segment from the book 
  • toc – table of contents
  • teachersguide – a guide oriented to educational needs
  • guide – a general guide oriented to book clubs or as a reader's guide
  • sample – a general sample such as a blad created for marketing

All samples and excerpts must

  • start with a valid ISBN-13 or ISBN-10, 
  • We will differentiate sample types based on addition of "sample", "excerpt", "toc", "teachersguide" or "guide".  If nothing is supplied we assume "sample".
  • we will record a number at the end, and use it to identify a specific sample. If no number is provided we assume that the sample number is "0".

The following names are acceptable

9781234567890_sample.pdf (or .epub)
9781234567890_sample_2.pdf
(numbering if there's a reason to have multiple samples for a title.)

9781234567890.pdf
(no underscore will be assumed to be a sample if it is in the sample directory.)
9781234567890_excerpt.pdf

9781234567890_toc.pdf

9781234567890_guide.pdf

9781234567890_teachersguide.pdf

FTP Structure

BNC BiblioShare allows you to submit your data in two ways: direct to your FTP account or using the File Uploads tab in your account's BiblioShare.org admin.  

FTP

When you sign up for BiblioShare, we'll provide you with FTP information. When you login into the ftp site you'll see four directories two of which, image and sample provide nested directories for different filetypes:

*Make sure your files go in the right directory or they will not be processed automatically.

BiblioShare.org

ONIX files and image files (named appropriately for the "image" directory – including BooksoniX clients) can also be uploaded on the BiblioShare website. When you log in, click on the Upload button in the navigation bar and select the appropriate item from the drop down:

  • delta (ONIX update files as defined above)
  • full (ONIX "all record" files as defined above – use delta if you're unsure)
  • image (image files following the rules for the "image" directory as defined above

On the upload screen, select the file you'd like to upload and then click "Upload/Validate". Note: Position files and files named for the "author" and "interior" sub-sub-directories can only be sent via FTP.

Reports

When you send ONIX files to BiblioShare, you'll receive an emailed import report and, if the import was successful, an update report. You can also log in to BiblioShare.org to view a more detailed file import report, as well as frequency, data elements, and quality reports.

Import Reports

The emailed import reports let you know if an individual file passed schema validation and made it into the BiblioShare database.

Import Failed

The Import Failed report lets you know that your ONIX file did not pass schema validation (see Appendix 3 below). If you receive this report, you should check the file, make the changes necessary so that it passes schema validation, and resubmit it to BiblioShare.  If you're unsure, contact biblioshare@booknetcanada.ca for assistance.

Import Success

When your ONIX file passes schema validation, you'll receive an Import Success report. This notification contains a list of errors and warnings. These errors and warnings are simply recommendations based on best practices which will improve your file quality. It's up to your company to decide whether it makes sense for your business to implement these changes or not.

Biblio Update Report

After receiving an Import Success report, you will receive a Biblio Update report confirming that the file has been loaded into the BiblioShare database. This report will tell you how many new ISBN records were added to BiblioShare and how many ISBN records were updated in that one file upload.

BiblioShare.org Reports

When you log in to BiblioShare.org, you can view a more detailed file import report, as well as frequency, data elements, and quality reports. 


APPENDIX ONE:  What is BiblioShare?

BiblioShare is BookNet Canada’s data aggregation service for ONIX, image, sample and position files that provides support to Canadian publishing and retail sales.

An easy way to understand the services we offer is to follow this train of thought:

  • publishers and distributors communicate with retailers using data files
  • the largest and most comprehensive data file standard used is the ONIX standard
  • BiblioShare takes the same ONIX file and image material that publishers and distributors supply to retailers and provides data services to other players in the Canadian supply chain, including The 49th Shelf, our own e-catalogue service BNC CataList, wholesalers (library and trade) as well as a number of other businesses.

Our goal is to create a high-quality aggregate of book metadata to help simplify the Canadian supply chain and promote book discovery by businesses and consumers.


Are you ready for BiblioShare?

1. If you don't create ONIX files

ONIX for Books is an XML-based standard that allows publishers to populate retailer and other businesses digital platforms with book information.  The standard enables a communication system that allows the sender to map their product and marketing knowledge as well as their business terms to a file that is sent to an end user who maps what they wish to support in their systems – computer to computer communication.  For more information about ONIX see Appendix 2 below.

BiblioShare only accepts bibliographic data as ONIX and if you don't currently support it the first step is decide if you need and should support it. Here's some things to check:

  • BookNet Canada recommends that all publishers fully understand how their metadata is distributed – so this is a good time to ask how your data gets to retailers.  Take stock and understand your current distribution process for information about your books.
  • Do you work with another business that creates ONIX?  Many distributors or digital asset management systems do and may be supplying ONIX on your books to their clients.  Check with them or ask us if they're already submitting files to BiblioShare. 
  • Do you use publishing software to track your business?  You should see if ONIX metadata creation is an available option.

If after that review you find you have no capacity to produce ONIX and have decided you want to develop it, you'll almost certainly need software to help.  There are a number of software suites that provide it. BiblioShare will accept feeds from any can support schema valid files. 

BookNet Canada supports one: BNC Webform, which supports enough data points to create a comprehensive record North American retailers can use without overwhelming the user.

Other file types:   BiblioShare also accepts a wide range of image files and position files (aka availability files).  Contact us for details.

2. If your company supports an ONIX feed apply now

Fill out this form and join:  https://www.booknetcanada.ca/biblioshare-sign-up   We'll set up an account and you can start anytime. 

3. if you have questions:

biblioshare@booknetcanada.ca

APPENDIX TWO: Manuals, Documentation and Resources

BookNet Canada material

Best Practices and EDItEUR's ONIX Overview

Using XML and doing validation

EDItEUR documentation

APPENDIX THREE:  XML Validation

Any sender of ONIX files should know how to ensure that what you send is valid as an XML document and it's a mandatory skill if you are developing an ONIX file as an export from a database.

An XML schema defines how an XML document can be built and can also be used to check the validity of an XML document.

In ONIX, the Document Type Definition (DTD) only validates the structure of the document, but the XML Schema Definition (XSD) validates both the structure and code values. Or, to put it another way, DTD checks the syntax of the XML document, while the XSD checks both syntax and semantics.

Schema validation is an important step that is often overlooked. BiblioShare requires that all files pass schema validation before they are loaded into the database and that helps us maintain a base level of quality of BiblioShare data. Doing your own XML validation will help you stay in control of your data. Aggregators often have to fix mistakes in ONIX files before they are loaded into their database.  Minor mistakes are fixed on the fly based on a reasonable guess that may not reflect publisher preferences. We believe that control should be in the hands of the data sender, and part of having that control is validating your files so that you can find any existing problems and fix them your way. A valid file can be loaded using standard XML programming.  An invalid file won't load and has to be fixed.  

You wouldn't publish a book without proofreading it first, would you? Schema validation is the same principle – proofreading for computer loadability. Own your data!

Schema validation is quick and easy. Follow the steps in DIY Schema Validation for Workmanlike ONIX.

APPENDIX FOUR:  BooksoniX Image Processing

Biblioshare will accept Cover, Interior and Author images named to the standard BooksoniX uses, which we understand as:

9781234567890-AA-B.jpg
where the number string is a valid ISBN-13, AA is a ONIX Code List 38 code value and B is a number used to differentiate multiples.

BiblioShare will accept the following codes defined by ONIX Code LIst 38:

04 / 05 / 06 / 07 will be processed as a "cover."

  • Numbering and multiple copies will NOT be preserved.
  • We only maintain a single cover image. If a new image is received it will replace the current version.
  • We prefer and expect to receive cover images named as "04" -- but if 2 files named as "cover" appear because of number variations or multiple code values the last one processed will become our archive copy. 

08 will be processed as an author image.

  • Numbering and multiple copies will be preserved.
  • If a new author image with identical number is received it will replace the current corresponding version

23 will be processed as an interior image.

  • Numbering and multiple copies will be preserved
  • A  new image of the same number replaces the current version.

24 & 25 will be processed as back covers (List 38 code for "back cover" & "high quality back cover")

  • Numbering and multiple copies will NOT be preserved.
  • Only a single back cover image is maintained. If a new image is received it will replace the current version.

All other codes will be ignored by our processing and will not become part of our archive.

Final note:   A file where the ISBN itself contains dashes will NOT be processed as a BooksoniX standard file, so this
978-1-23456-789-08-1.jpg 
would not be recognized as an "08" author file but would process in our system as a cover. This should not be an issue as our understanding is that BooksoniX does not store images this way.

APPENDIX Five:  Coresource Image Processing

Biblioshare will accept Covers and Interiors as named by the standard used by Coresource:

Covers named as 9781234567890_FC.jpg  are accepted in directory \image

Interiors named as 9781234567890_iart.jpg OR 9781234567890_001_iart.jpg are accepted in directory \image OR \image\interior


Contact: biblioshare@booknetcanada.ca

Feel free to contact us at biblioshare@booknetcanada.ca with any questions regarding BiblioShare.