Item Document

In the technology overview section, we briefly discussed the ideas behind a document-oriented database and how it is used in Scrapbook101. In this section we describe one of the key document types stored in the document-oriented database, the item document.

Our design approach is model-first approach meaning we start with a prototype item document in JSON that represents one Scrapbook101 item. From this prototype document, the code class Item.cs is defined in our Visual Studio project representing this item document.

Overview

Below is the prototype item document that describes one Scrapbook101 item in JSON. The document data store will contain one document that looks like this for every Scrapbook101 item. This item document is one of the two document types (distinguished by the type field) stored in the document datastore. The other document type is the Category Document.

The values of the fields in the key-value pairs aren’t important below, only the structure is. Following the JSON are descriptions of each field.

{
    "assets": [
        {
            "name": "name",
            "size": 10000
        }
    ],
    "assetPath": "path to assets",
    "category": "category",
    "categoryFields": {
    },
    "dateAdded": "timestamp",
    "dateUpdated": "timestamp",
    "description": "description",
    "geoLocation": {
        "type": "Point",
        "coordinates": [
            43.5290298461914, 
            12.1621837615967
        ]
    },
    "id": "GUID",
    "location": "location name",
    "rating": "rating",
    "title": "title",
    "type": "scrapbook101Item",
    "updatedBy": "identifier, email or name"
}

Description of fields

Fields not marked as Required are not required.

assets

A list of assets associated with the Scrapbook101 item. Can be null, meaning no assets are associated with the item.

Default: null
Format: A JSON array of objects containing two strings and a number:

name: The name of the asset.
Format: A string, e.g., "Folder.jpg".
size: The size in bytes of the asset.
Format: A number, e.g., 20056.

assetPath

This is the path to any digital assets associated with the item. For example, there might be images, PDFs or other documents that give context about the item. Associating assets is not necessary if you plan to implement Scrapbook101 without any assets. Part of the spirit behind Scrapbook101 however is to provide strong visual cues for remembering an item as well as archiving data associated with it, so at least one image for each Scrapbook101 is recommended.

Default: null
Format: A string, e.g., "year2018/jan-10" or "assets/2018/2018-12-10".

category

One of the category values described in Category Document. A Scrapbook101 item must be assigned to a category.

Required
Format: A string, e.g. "Books".

categoryFields

Fields specific to the category selected for the Scrapbook101 item. See the Category Document for more information. Each category has a fixed set of fields.

Default: Depends on the category chosen.
Format: An object containing key-value pairs.

For example, for a Scrapbook101 book item, the categoryField object would look like the following:

"categoryFields": {
    "author": "author name",
    "genre": "genre",
    "year": "year",
    "synopsis": "synopsis",
    "theme": "theme"
}

dateAdded

This value is automatically inserted by code upon initial creation of an item and then never changed.

Format: A string that is an ISO 8601 date and time, e.g., "2018-06-07T00:00:00".

dateUpdated

This value is automatically inserted by code. On initial creation of an Scrapbook101 item, dateUpdated equals dateAdded. When an item is edited, dateUpdated is updated with the correct timestamp.

Default: Initially equal to dateAdded.
Format: A string that is an ISO 8601 date and time, e.g., "2018-06-07T00:00:00".

description

Information about the Scrapbook101 item that isn't already captured in other fields. This field provides the context of why the item is important. Descriptions longer than a couple hundred words should be added as assets.

Default: null
Format: A string, e.g. "The best book I've read in 2018...".

geoLocation

If you have a Bing Maps Key and it is specified in the web.config file, then location values are converted into latitude and longitude coordinates (geocoded) to allow for more flexible location searches.

Default: null
Format: An object that contains a string and an array:

type: The type of geocode. Scrapbook101 stores points, so this value is always "Point".
coordinates: An array of two numbers, the first is longitude and the second is latitude. For exmple, [43.5290298461914, 12.1621837615967].

id

This is a GUID auto-generated upon insertion into the document store.

Required
Format: A GUID, e.g., "d26f6d16-591e-4ae2-9072-d7ba113ec454".

location

This field is a friendly name of the location that is relevant for the Scrapbook101 item. It is not required but is helpful. It is important to be consistent with how you enter values to make searching easier.

Default: null
Format: A string, e.g. "Seattle, WA" or "101 Main St., Seattle 98103, USA".

rating

A rating of the Scrapbook101 item, if applicable. The rating system will be unique for each implementation. The test data provided with Scrapbook101 uses a rating of 1 - 5.

Default: null
Format: A number, e.g. 3.

title

A descriptive title for the Scrapbook101 item. For example, if item is a book, use all or part of the book title.

Required
Format: A string, e.g. "Brief Answers to the Big Questions".

type

Describes the type of record. If your documents are stored in a data store with other documents from other applications using an id field, then type helps distinguish Scrapbook101 records uniquely. There are two types of documents, item documents and category documents.

Required
Format: A string equal to "scrapbook101Item".

updatedBy

This could be a user name or ID. For example, if you implement a authentication scheme based on Windows Live, Facebook, or Google, you can use the user's email or ID in this field.

Default: null
Format: A string, e.g. "somename@someemail.com".

JSON schema

Optional.

The description of the fields above is usually sufficient for programmers looking for an overview of the item document’s structure, its fields and their values. Another way to approach “documenting” the Scrapbook101 item document is with a JSON schema, which would provide a more precise description of the JSON. Besides describing the JSON item document, the schema could also be used to validate any new block JSON as representing a valid item document or not.

In the Scrapbook101 application, validation is done implicitly as the JSON is serialized from a class object and deserialized into a class object. In other words, documents in our data store are valid JSON because they are created and edited via a fixed class (see for example the Item.cs class). In this situation, a JSON schema isn’t as critical because we won’t be encountering JSON that isn’t in the context of this application.

Consider the following simplified item document:

{
    "category": "category",
    "description": "description",
    "id": "GUID",
    "rating": "rating",
    "title": "book title",
    "type": "scrapbook101Item"
}

Using a schema generator like JSONschema.net, a possible schema describing the simplified item document might look like the following (truncated to show just the initial part of the schema):

{
   "definitions": {},
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://example.com/root.json",
   "type": "object",
   "title": "The Root Schema",
   "required": [
     "item"
   ],
   "properties": {
     "item": {
       "$id": "#/properties/item",
       "type": "object",
       "title": "The Item Schema",
       "required": [
         "category",
         "id",
         "title",
         "type"
       ],
       "properties": {
         "category": {
           "$id": "#/properties/item/properties/category",
           "type": "string",
           "title": "The Category Schema",
           "default": "",
           "examples": [
             "category"
           ],
           "pattern": "^(.*)$"
         },
...
}