bitmark JSON Bit Object Reference

Introduction

Below is a real-world example of a bitmark JSON object with detailed explanations. This oject is used as a container for all variants of a bit (like markup description, JSON description in the bit property, ready for extensions, like bitmark xml, QTI, DITA, ... descriptions) and for additional system, sharing or private information.

markup, bit, meta, system and private

At the root level of the Bit object, you will find up to five properties:

{
    "markup": "[.multiple-choice-text]...",
    "bit": {
        "type": "multiple-choice-text",
        ...
        "private": {
            ...
        },
        "meta": {
        ...
        }
    },
    "sharing": {
        ...
    },

    "system": {
        ...
    },
    "private": {
        ...
    }
}

Properties	Data Type, Description
markup	String, optional
	Contains the original bitmark Markup that was used to construct this Bit. As Bits can be created in various ways, not just from markup, this property can be missing entirely.
	However, if the Bit is created from markup, the markup is kept to recreate the whole object at any given point in time (all properties, especially the content of the bit property). Whenever a newer version of markup or an improved markup parser becomes available (bug fixes, new features, additional meta-data, ...), new versions of Bits can get generated from this markup.
bit	Object
	Contains the content that is displayed to the user. As JSON does not support polymorphism, the differences between the different types of Bits is restricted to this node. See the Bit Types Reference
meta	Object, optional
	Contains the meta data that comes along with this bit.
private	Object, optional
	This optional property contains private data of the author of that bit. Please see here for details.
system	Object, optional
	This optional property contains system information, like ouput from the parser, version, .... Please see here for details.

Set meta Properties [/meta/...]

To set a property with bitmark Markup. Please use the [/meta/...] tag. The tag contains a JSON Pointer to the desired property and a value.

[/meta/context: business]

For boolean properties, the value can be ignored. In this case, the value is considered to be true.

[/meta/isFree]

Is the equivalent to

[/meta/isFree: true]

For setting values in an arry, just repeat setting a value to the array property.

[/meta/ageRange: 18]
[/meta/ageRange: 969]

meta

The meta objects contains the following properties.

context, subject, topics

    "meta": {
        ...
        "context": "business",
        "subject": "Expats in Switzerland - How to do successful business in Switzerland. - How to write a Motivational Cover Letter - Tips and Tricks.",
        "topics":  [ "Motivational Cover Letter", "Résumé/CV" ],
         ...
    }

bitmark JSON	Data Type, Description
context	String, optional
	Contains the high level context. The valid values for context are strictly defined. The API will reject any other values:
	business, personal, academic, kids, travel, immigration
subject	String, optional
	Contains a free form text. This text is never shown to the user and is aimed at the AI backend to classify the content, find related content and show good search results. It is usually constructed from the related static Article-Bit and the chapter titles leading to this bit.
topics	Array of Strings, optional
	Contains typical topics used in learning material. Many publishers use their own system. Mainly depending on their specialisation. Please feel free to use your own system. If you use a hierarchy, sub-categories, ..., please combine these values, separated by a "-". There is some AI magic in the API to map different systems.
	"Animals", "Animals - Great Apes", "Greeting people"

For high quality content (marked as such in the store object), these properties must be present and contain high quality data.

These properties don't have their own short markup tags (one letter special character).

Tip

bitmark JSON properties can be set by using markup. To set a certain property, you wrap it with an -Tag. For example, [/meta/context: business] sets the context property to the value "business".

Note

Please let us know, if there is a context, skill, ... missing.

complexity, grade, ageRange

This is the complexity of the Bit.

    "meta": {
        ...
        "complexity": "intermediate",
        "grade": "4",
        "ageRange": [18, 969],
        ...
    }

bitmark JSON	Data Type, Description
complexity*	String, optional*
	"basic", "intermediate", "complex"
grade*	String, optional*
	This is the grade (school year).
ageRange	Array of Integer of length = 2, optional
	Contains the age range for this content: [from age, to age]. Use 969 for open end. See why

For high quality content (marked as such in the store object), these properties must be present and contain high quality data.

duration

This is the expacted average reading/learning duration.

    "meta": {
        ...
        "duration": "PT2M10S",
        ...
    }

Duration in ISO_8601

maxScore

This is the maximum score a user can achieve with this quiz.

    "meta": {
        ...
        "maxScore": 20,
        ...
    }

maxScore = 0 indicates that the result can be used as a poll (no result is returned, but the inputs are collected).

language

Language of the bit.

    "meta": {
        ...
        "language": "en",
        ...
    }

bitmark JSON	Data Type, Description
language*	String
	This is the language a Bit is written in.
	In language learning, this is the language of the hints, learning objectives or explanations when written in the native language of the student.
	In general, two letter language codes (ISO 639-1 codes) are used.
	In some cases, the language declaration needs to be more specific. Language localisation is used in such case (e.g. "de-CH").
	For language learning Bits, please note the learningLanguge property.

For high quality content (marked as such in the store object), these properties must be present and contain high quality data.

Sometimes, hints, learning objectives or explanations are also translated to the learning language. At the moment, this type of quizzes cannot described fully content-first by the bitmark standard. As a work around, ypu might tag the translations as emphazised. We are not happy about that.

set

    "meta": {
        ...
        "set": {
            "item": [ { "type": "text", "text": "A10" } ],
            "lead": [ { "type": "text", "text": "Exercise" } ],
            "title": [ { "type": "text", "text": "Traveling around the World" } ],
            "isGenericTitle": false,
            "isProgress": true,
            "setRef": "a10-3243253-2",
            "setIndex": 0
        },
        ...
    }

Bits that belong to a set of bits, contain a set property.

tags

Tags are used to highlight recurring subjects in a book or collection of books. This is an additional way to structure content. Let's imagine a German grammar book that is strictly organized in chappters according to the typical subjects of German grammar. The author keeps using examples around sports, especially football. In this case, to use a #sports and a #football tag would make sense. Tags are used for searching/filtering bits of a book.

    "meta": {
        ...
        "tags": ["#sports", "#football"],
        ...
    }

Tag names might be displayed to the user and must be in the language of the book. Tag names must start with a "#".

Language Learning

The following properties are only present in bits used for language learning.

    "meta": {
        ...
        "learningLanguage": "de-CH",
        "languageSkills": ["reading"],
        "levelILR": ["1", "1+"],
        "levelCEFR": ["A2", "B1"],
        "levelACTFL": ["IM", "IH"],
        "grammar": ["Verbs: Present"],
        ...
    }

learningLanguage

These are levels for language learning. Learning material sometimes belong to more than one level.

bitmark JSON	Data Type, Description
learningLanguage	String
	For language learning material, this is the language to be learned/teached. In general, two letter language codes (ISO 639-1 codes) are used. In some cases, the language declaration needs to be more specific. Language localisation is used in such case (e.g. "en-US").
	If the learningLanguage property is not present or empty, the value of language is used.

languageSkills

bitmark JSON	Data Type, Description
languageSkills	Array of Strings, optional*
	"reading", "speaking", "listening", "writing", "translation", "audio translation", "interpretation", "intercultural communication", "transcreation", "other"

levelILR, levelCEFR and levelACTFL

bitmark JSON	Data Type, Description
levelILR	String, optional*
	ILR Also see table below
levelCEFR	String, optional*
	CEFR Also see table below
levelACTFL	String, optional*
	ACTFL Also see table below

In the Book JSON, all three levels are present. If you use our API, at least one level must present at the creation of the Bit. The others are approximately calculated.

For high quality content (marked as such in the store object), these properties must be present and contain high quality data.

ILR	CEFR	ACTFL
0, 0+	A1	NL, NM, NH
1	A2	IL, IM
1+	B1	IH
2, 2+	B2	AL, AM, AH
3, 3+	C1	S
4, 4+	C2	D

grammar

bitmark JSON	Data Type, Description
grammar	Array of Strings, optional*
	Many publishers use their own system to classify grammar. Some more, some less detailed. Please feel free to use your own system. There is some AI magic in the API to map different systems. Grammar values might be displayed to the user. So please make them short and use title case notation. Some common API and data models call this "skills"! For high quality content, this property must contain "-" if a grammar topic is not meaningfully applicable.
	"Verbs: Past Imperfect", "-"

sharing

The sharing objects defines the owner (creator), copyright holder, origin Books and access rights.

    "sharing": {
        "owner": {
            "fullName": "Thomas Gabathuler",
            "nicKName": "Gaba.",
            "gid": "com.getmorebrain.u0"
        },

        ...
    }

thisBook, originBook

Bits that are requested from an API Endpoint that includes a book, thisBook includes meta data from this book. Bits might also contain meta data from an origin book. This is typically the book a user bought from a publisher.

thisBook and originBook might bouth be missing entierly. A bit can also exists for itself. Both properties might also contain the same book.

A typical example, where thisBook and originBook differ, is a bit coming from a school book that was first stored and then retrieved from a user's notebook. In this case, orginBook points to the original school book. thisBook points to the user's notebbok.

The originBook and thisBook might contain a chapterPath property that contains the path of a bit it has inside its origin/this book.

Not every Bit is contained by a book, so, these fields might be missing completely.

    "sharing": {
        ...
        "originBook": {
            "id": "",
            "externalId": "",
            "type": "book",
            "subType": "book",
            "isLiveBook": false,
            "isSmartBook": false,
            "isPublic": false,
            "isHighQuality": true,
            "shopURL": "https://books.markup.com/shop/a_publisher/0923480923i4/",
            "shareURL": "https://books.markup.cloud/reader/book/0923480923i4/",
            "chapterPath": [
                { "item": [], "title": [ { "type": "text", "text": "Origin Book Title" } ], "isGenericTitle": false, "level": 0, "isProgress": false, "ref": "a1298789" },
                { "item": [ { "type": "text", "text": "2" } ], "title": [ { "type": "text", "text": "Chapter Two" } ], "isGenericTitle": false, "level": 1, "isProgress": true,  "ref": "a1298811" } ] },
                { "item": [ { "type": "text", "text": "2.7" } ], "title": [ { "type": "text", "text": "Chapter Two Seven" } ], "isGenericTitle": false, "level": 2, "isProgress": true,  "ref": "a1298923" } ] }
            ]
        },
        ...
    }

Important

Every Bit can be part of several books. However, it only inherits meta data from one book, its "master book." This is the book referenced here.

book	Data Type, Description
type	String
	"book" indicates a fully featured book (with table of content, chapters, ...), displayed with a book reader interface.
	"collection" indicates a list of bits. A collection has no chapters, table of content, ... Collections are displayed with a search/filter interface.
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.
isPublic	Boolean
	Indicates public content. No need to check the store or an account for rights.
isHighQuality	Boolean
	Indicates high quality content generated by professionals. Guaranteed free of mistakes and fully described by meta data.
shopURL	String
	Reference to the book that contains this bit. The url points to the shop. Use this url to share a link to this book in the shop.
shareURL	String
	Reference to the book that contains this bit. The url points to the book. If it is not free and not owned, a preview with a buy button is shown. Use this url to share a link to this book (over mail, messengers, ...).
chapterPath*	Array of Chapter Objects
	Contains the chapter hierarchy of this bit. Not every Bit is contained by a book, so, this field might be missing.

chapterPath

chapterPath entries have very similar properties like the toc (table of content) of a book. Every chapter has a level. The first object (level 0) is the book itself.

See toc entry for detailed explanation of the properties.

Example:
A bit requested from /bits/12344 does contain an empty chapterPath property.
A bit requested from /books/4636/bits/12344 does contain the path to the bit inside the book 4636

    "sharing": {
        ...
        "chapterPath": [
            { "item": [], "title": [ { "type": "text", "text": "Origin Book Title" } ], "isGenericTitle": false, "level": 0, "isProgress": false, "ref": "a1298789" },
            { "item": [ { "type": "text", "text": "2" } ], "title": [ { "type": "text", "text": "Chapter Two" } ], "isGenericTitle": false, "level": 1, "isProgress": true,  "ref": "a1298811" } ] },
            { "item": [ { "type": "text", "text": "2.7" } ], "title": [ { "type": "text", "text": "Chapter Two Seven" } ], "isGenericTitle": false, "level": 2, "isProgress": true,  "ref": "a1298923" } ] }
        ],
        ...
    }

isFree

Indicates if this Bit can be used for free, even if it is part of a fee-based book. This flag is often used together with the isPreview flag, to provide a preview that is actually working.

    "sharing": {
        ...
        "isFree": false,
        ...
    }

isPublic

Indicates if this Bit can be used for free and publicly (even if isFree is set to false). Public books can be read even without an account.

    "sharing": {
        ...
        "isPublic": false,
        ...
    }

isPreview

Indicates if this Bit is to be shown as part of a preview chapter. If this is an interactive bit (quiz), this does not automatically mean that you can also interact with this bit. The interactive quiz is displayed read-only.

See next property, if you want free and interactive bits.

    "meta": {
        ...
        "isPreview": false,
        ...
    }

copyright

    "sharing": {
        ...
        "copyright": "© 2012 by A Publisher International Ltd., Zurich, Switzerland",
        ...
    }

Copyright in human readable form. Can be used to be displayed to the end user.

publisher

    "sharing": {
        ...
        "publisher": {
            "name": "A Publisher International Ltd., Zurich, Switzerland",
            "href": "https://www.a_publisher.com",
            "mail": "comments@a_publisher.com"
        },
        ...
    }

Publisher info. The fields href and mail are optional.

license

    "sharing": {
        ...
        "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]
        },
        ...
    }

License info. All fields are optional. Including the "license" container

authors

    "sharing": {
        ...
        "authors": [
            {"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"},
        ],
        ...
    }

Human readable authors info. Usually not used to be displayed to the end user. All fields are optional. Including the "authors" container

shareURL

The url points to this Bit. If it is not free, owned or purchased, a preview with a buy button is displayed. Use this url to share a link to this Bit.

    "sharing": {
        ...
        "shareURL": "https://a_publisher.com/bit/b1234",
        ...
    }

system

The system object is read only. It is set by the API.

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

        "version": "2.0",

        "parser": {
            "name": "markup.json.js",
            "version": "1.0",
            "status": "OK",
            "fatalError": "",
            "errors": [],
            "warnings": []
        }
    },
    ...

private

    "private": {
        "id": "HJ_98798723",
        "ui_hint": "underline",
        "legacy_hints": {
            "paper-and-pen-instruction": "Underline the correct solution with your pen."
        },
        "author_id": "m.mustermann2",
        "legacy-title-image": "https://a_publisher.com/dolphins.jpg",
        "print-title-image": "https://a_publisher.com/dolphins.tiff",
        "approvedAt": "23.3.2018",
        "approvedBy": "JH",
        "item_number":"e2110"
    },

Private info. This node can be freely used by the publisher for any internal use. There are no restrictions (besides being 100% valid JSON, of course).

Timestamps

Timestamps are in the ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

Information about time zones in timestamps, please see.