Skip to content

bitmark JSON Book Object Reference

Introduction

Below you'll find an example of a bitmark JSON Book.

bitmark JSON Book Structure and Properties

{
    "title": "Book Title",
    "subtitle": "Book Subtitle",
    "subject": "German as a Foreign Language",
    "format": "Integrated course and work book",
    "description": "Short description of this book by the publisher.",

    "type": "book",
    "format": "bitmark--",
    "kind": "collection",
    "isLiveBook": false,
    "isSmartBook": false,
    "isHighQuality": true,

    "coverImage": {
        "width": 700,
        "height": 1000,
        "src": "https://cdn.bitmark.cloud/books/com.firstpub.book98789/cover.jpg",
        "src1x": "https://cdn.bitmark.cloud/books/com.firstpub.book98789/cover@1x.jpg",
        "src2x": "https://cdn.bitmark.cloud/books/com.firstpub.book98789/cover@2x.jpg",
        "src3x": "https://cdn.bitmark.cloud/books/com.firstpub.book98789/cover@3x.jpg",
    },

    "language": "en-US",
    "learningLanguage": "de",

    "authors": [
        { "name": "Philippe Pointet", "role": "" , "morebooksByThisAuthor": []},
        { "name": "Brita Cristea", "role": "Scientific Review" },
        { "name": "Brita Cristea", "role": "English Review" },
        { "name": "Thomas Gabathuler", "role": "Design and Layout" }
    ],

    "publisher": {
        "name": "A Publisher International Ltd., Zurich, Switzerland",
        "href": "https://www.a_publisher.com",
        "mail": "comments@a_publisher.com",
        "logo": {
            "width": 125,   //width max. 125
            "height": 40,   //height must be exactly 40
            "src": "https://cdn.bitmark.cloud/books/com.firstpub.book98789/pub_logo_small.jpg",
            "src1x": "https://cdn.bitmark.cloud/books/com.firstpub.book98789/pub_logo_small@1x.jpg",
            "src2x": "https://cdn.bitmark.cloud/books/com.firstpub.book98789/pub_logo_small@2x.jpg",
            "src3x": "https://cdn.bitmark.cloud/books/com.firstpub.book98789/pub_logo_small@3x.jpg",
    },

    "series": {
        "title": "German as a Foreign Language",
        "id": "com.firstpub.e0111",
        "numberInSeries": 1
    },

    "shareURL": "https://books.bitmark.cloud/reader/book/0923480923i4/",
    "sourceURL": "",
    "shopURL": "https://books.bitbook.com/a_publisher/0923480923i4/",

    "id": "com.firstpub.book98789",
    "sku": "HAgHQiZaAXqxkMSSR",
    "isbn13": "978-3833936593",

    "license": {
        "name": "A Publisher license",
        "remarks": "For the exclusive use of A Publisher language centers",
        "source": "https://www.a_publisher.com/licensee/",
        "yearRange": [2012, 2017]
    },

    "publications": [
        "First published 2012",
        "Revised 4th edition 2017"
    ],

    "printPageCount": 120,

    "branding": {
        "lightTheme": {
            "primaryColor": "#0E84EF",
            "secondaryColor": "#9BD0FF",

            "highlightColor": "#F8E71C",
            "textColor": "black",
            "backgroundColor": "white",
            "bulletColor": "#0E84EF",
            "bulletGlyph": "•"
        },

        "darkTheme": {
            "primaryColor": "#0E84EF",
            "secondaryColor": "#9BD0FF",

            "highlightColor": "#F8E71C",
            "textColor": "white",
            "backgroundColor": "#565656",
            "bulletColor": "white",
            "bulletGlyph": "•"
        },
    },

    "private": {
        "release": "2., veränderte Auflage"
    }

}

Type Properties

Property Data Type, Description
kind String
"book" indicates a fully featured book (with table of content, chapters, ...), displayed with a book reader interface.
"soup" indicates unstructured collection of bits. A soup has no table of content, ... Soups are displayed with a search/filter interface. A typical application is a collection of exams.
"collection" indicates a book only availabe as print. It might contain no content or some sample content like a free chapter. Collections often relate to paperbook via the relatedBookId property.
"learning-path" indicates a book only availabe as print. It might contain no content or some sample content like a free chapter. Collections often relate to paperbook via the relatedBookId property.
"pdf" indicates a book availabe as Adobe pdf.
isLiveBook Boolean
Live Books are constantly growing and can be followed. Followed books send notifications if new content becomes available.
Example: YouTube channels, quizzes based on real news, ...
isSmartBook Boolean
Smart Books are AI driven and can give didactically valuable feedback and/or provide a personal learning experience.
isHighQuality Boolean
Indicates high quality content generated by professionals. Guaranteed free of mistakes and fully described by meta data.

shopURL, shareURL, sourceURL

Use these urls to share a link to this book. Typical examples include sending this link via e-mail, share it via social media or publish it on a webpage. The shopURL directly links to a shop detail page. The shareURL a publicly available copy of the book.

coverImage

The preferred aspect ratio for e-book covers is 7:10 (width:height). However, the real aspect ratio is defined by the original book cover.

As we need covers to be in high resolution, at least 700 pixels x 1000 pixels is recommended. For other aspect ratios, please just make sure, images are at least 700 pixels wide. The height results from scaling without distortion.

In order to provide the expected quality on the platform, we reject images with a width of less than 420 pixels.

Full Book

When requesting a book from the API, the book object contains additional, read-only properties. These properties summarize and collect properties from the whole book.

{
    ...
    "toc": [
        {"type": "chapter", "item": [], "lead": [], "title": "Preface", "isGenericTitle": false, "level": 2, "isProgress": false, "ref": "com.firstpub.c20000" },
        {"type": "chapter", "item": [ { "type": "text", "text": "1", "lead": [], "title": "Traveling", "isGenericTitle": false, "level": 1, "isProgress": true, "ref": "com.firstpub.c20001" },

        {"type": "chapter", "item": [ { "type": "text", "text": "1.1", "lead": [], "title": "Introduction", "isGenericTitle": false, "level": 2, "isProgress": true, "ref": "com.firstpub.c20002" },
        {"type": "article", "item": [], "lead": [], "title": "Around the world", "isGenericTitle": false, "isProgress": true, "ref": "com.firstpub.09823409h40" },
        {"type": "article", "item": [], "lead": [], "title": "Image", "isGenericTitle": false, "isProgress": true, "ref": "com.firstpub.09823409h41" },

        {"type": "chapter", "item": [ { "type": "text", "text": "1.2", "lead": [], "title": "Travel Quizzes", "isGenericTitle": false, "level": 2, "isProgress": true, "ref": "com.firstpub.c20003" },
        {"type": "multiple-choice", "item": [ { "type": "text", "text": "A1a", "lead": [ { "type": "text", "text": "Traveling", "title": "What are the capital cities of the following countries?", "isGenericTitle": false, "isProgress": true, "ref": "com.firstpub.09823409h22" } ] } ] },
        {"type": "multiple-choice", "item": [ { "type": "text", "text": "A1a", "lead": [ { "type": "text", "text": "Traveling", "title": "What are the countries with the following capital cities?", "isGenericTitle": false, "isProgress": true, "ref": "com.firstpub.09823409h23" } ] } ] },

        {"type": "set", "item": [ { "type": "text", "text": "A10", "lead": [ { "type": "text", "text": "Exercise", "title": "Traveling around the World", "isGenericTitle": false, "isProgress": true, "setRef": "a10-3243253-2", "ref": "com.firstpub.s20000" } ] } ] },
        {"type": "multiple-choice", "item": [ { "type": "text", "text": "A10a", "lead": [ { "type": "text", "text": "Traveling", "title": "What are the capital cities of the following countries?", "isGenericTitle": false, "setIndex": 0, "setRef": "a10-3243253-2", "ref": "com.firstpub.09823409h22", "isProgress" } ] } ]: true },
        {"type": "multiple-choice", "item": [ { "type": "text", "text": "A10b", "lead": [ { "type": "text", "text": "Traveling", "title": "What are the countries with the following capital cities?", "isGenericTitle": false, "setIndex": 1, "setRef": "a10-3243253-2", "ref": "com.firstpub.09823409h23", "isProgress" } ] } ]: true }

    ],
    "compatibility": {
        ...
    },
    "summary": {
        ...
    },
    "system": {
        "creationDate": "2018-04-23T18:25:43.511Z",
        "modificationDate": "2018-04-23T18:25:43.511Z",

        "parser": "bitmark.json.js",
        "parserVersion": "1.0"
    },
    ...
}

toc (read-only)

toc contains the table of content of this book. It is a calculated value and therefore read-only.

toc never contains certain bits like ".book", ".summary".

toc Entry

type, item, lead, title, ref, setRef, setIndex, isProgress, isGenericTitle

Type contains the type of the bit.

Item contains the "chapter number".

The title property of a chapter can be empty. This is commonly used to have chapters without titles. Empty titles never show up in the table of content (toc) of a book. It must never create an empty space in the user interface.

Ref contains the id of a bit. Use the API to retrieve the content of the corresponding bit.

setRef contains the set id of a bit, in case, the bit belongs to a set. Use the API to retrieve the full set including all bits. setIndex contains the index of a bit within the set.

Bits with isProgress set to false, are not accounted for user progress in reading the book. Table of content, preface, appendices, ... are usually marked as as such. Often, this property is also used to reasonable layout of the content and of the table of content of a book (for example giving less weight to lesser relevant chapters or collpasing content).

isGenericTitle is set for toc entries that needs to display a placeholder description in the toc instead of a title that describes the content. For example, a .article&image bit, only containing an image, but no text at all, would have set isGenericTitle to true and a title "Image".

Default is true.

compatibility (read-only)

Compatibility is a calculated value and therefore read-only. If you provide a compatibility property when creating or updating a book, it is ignored and overwritten with the newly calculated value.

The properties of the compatibility object let your app decide if bitmark JSON is compatible with your app and optimized for a certain device.

{
    "compatibility": {
        "type": ["article", "article&video-link:youtube.com", "cloze", "interview&image"],
        "textCommonDenominator": "bitmark--",
        "imageResolutions": ["1x", "2x", "3x"],
        "imageResolutionsCommonDenominator": ["1x", "2x"],
    },
    ...
}

publications

    "sharing": {
        ...
        "publications": [
            "First published 2012",
            "Revised 4th edition 2017"
        ],
        ...
    }

Human readable publications info. Can be used to be displayed to the end user. All fields are optional. Including the "publications" container

summary (read-only)

Properties from the whole content (all bits) are collected in the property "summary". All properties (except for ageRange) don't contain any duplicate values.

Summary is a calculated value and therefore read-only.

{
    ...
    "summary": {
        "tags": ["#DAZ"],
        "groups": [],
        "grade": [],
        "complexity": ["basic", "intermediate", "complex"],
        "levelCEFR": ["A1", "A2"],
        "learningLanguage": ["de"],
        "language": ["en-US"],
        "copyright": ["© 2012 by A Publisher International Ltd., Zurich, Switzerland"],
        "context": ["business"],
        "subject": ["Expats in Switzerland - How to do successful business in Switzerland. - How to write a Motivational Cover Letter - Tips and Tricks."],
        "topic":  ["Motivational Cover Letter", "Résumé/CV"],
        "grammar": ["Verbs: Present", "Verbs: Past"],
        "skills": ["reading", "writing", "listening", "speaking"],
        "ageRange": [18, 969],
        "bitAuthors": [
            {"name": "A Publications Ltd., New York", "role": "Design, Layout and Cartoons"},
            {"name": "CPI books, Ulm, Germany", "role": "Printed and bound"},
            {"name": "© dreamstime.com, © fotolia.com, © iStockphoto.com and by A Publications Ltd., Bern", "role": "Pictures"},
        ],
    },
    ...
}