Nunaliit Tutorial: Adding a Schema

What is a schema?:

A schema provides guidelines for Nunaliit in the creation, editing and viewing of documents. They allow atlas builders a means to define what data to collect and how it should be viewed by the user. However, it’s important to note that how a schema is defined shouldn’t be viewed as hard set rules, but rather suggestions of the type of content expected in a document.

By default each atlas provides a demo document schema, a demo comment schema and a demo media schema. These schemas provide a new atlas builders a place to start testing out the functionality of the atlas right away. However, if you continue to use Nunaliit, you will likely need to build your own schema for a specific project. This tutorial provides the steps for creating your own schemas.

Designing a schema definition:

Typically when designing a schema, an atlas builder should first consider what data will be collected, and how to segment it into it’s core components. For example, an atlas which focuses on financial institutions, may contain data on banks, bank staff, bank clients, and transactions. This data can be simplified into three schemas: bank, person, and transaction. Notice that both bank staff and bank clients are merged into a single person schema, since their data will likely contain similar information. See below for an example of the fields needed for these three schemas.

schemadesign

Schema designs for Bank, Person and Transaction schemas.

Add a schema to the atlas:

To add a new schema to the atlas, you will need to run the command ‘nunaliit add-schema –id schemaid’ from the root directory of the atlas (similar to how you would run the update or run commands).

 e.g. ../nunaliit2-couch-sdk-2.2.6/bin/nunaliit add-schema --id bank

This command will create a new schema, which is added to the atlas’ docs folder with the name ‘schema.groupname_schemaid’. Within the new schema’s directory, you will see the required files which define the structure of a schema. Initially these files contain the basic structure of the schema, and will need to be updated to represent the schema design mentioned above.

schemadircontents

List of files within a schema directory

schema.testatlas_bank/
├── brief.txt
├── create.json
├── csvExport.json
├── definition.json
├── display.txt
├── export.json
├── form.txt
├── _id.txt
├── isRootSchema.json
├── label.txt
├── name.txt
├── nunaliit_schema.txt
├── nunaliit_type.txt
└── relatedSchemas.json

Updating the schema’s design can be performed by defining the structure of the schema in the definition.json file. Instructions on how to create defintion.json files, including a complete list of field options, can be found on the atlas builder wiki pages.

Using the schema designs shown above, I’ve included three examples of the definition files for the bank, person and transaction schemas.

Bank Schema Definition:

{
    "group": "testatlas"
    ,"id": "bank"
    ,"label": "Bank"
    ,"relatedSchemas": [ ]
    ,"initialLayers": [ "public" ]
    ,"attributes":[
    {
        "type":"string"
        ,"id":"name"
        ,"label":"Name"
        ,"includedInBrief":true
    }
    ,{
        "type":"string"
        ,"id":"branch_number"
        ,"label":"Branch #"
    }
    ,{
        "type":"string"
        ,"id":"address"
        ,"label":"Address"
        ,"textarea": true
    }
    ,{
        "type":"string"
        ,"id":"phone_number"
        ,"label":"Phone #"
    }
    ,{
        "type": "array"
        ,"elementType":"reference"
        ,"id":"employees"
        ,"label":"Employees"
    }
    ,{
        "type":"checkbox"
        ,"id":"atm"
        ,"label":"ATM location?"
    }
    ]
}

Person Schema Definition:

{
    "group": "testatlas"
    ,"id": "person"
    ,"label": "Person"
    ,"relatedSchemas": [ ]
    ,"initialLayers": [ ]
    ,"attributes":[
    {
        "type":"string"
        ,"id":"name"
        ,"label":"Name"
        ,"includedInBrief":true
    }
    ,{
        "type":"string"
        ,"id":"address"
        ,"label":"Address"
        ,"textarea": true
    }
    ,{
        "type":"string"
        ,"id":"phone_number"
        ,"label":"Phone #"
    }
    ]
}

Transaction Schema Definition:

{
    "group": "testatlas"
    ,"id": "transaction"
    ,"label": "Transaction"
    ,"relatedSchemas": [ ]
    ,"initialLayers": [ ]
    ,"attributes":[
    {
        "type": "reference"
        ,"id":"payer"
        ,"label":"Payer"
    }
    ,{
        "type": "reference"
        ,"id":"payee"
        ,"label":"Payee"
    }
    ,{
        "type":"string"
        ,"id":"amount"
        ,"label":"Amount"
    }
    ,{
        "type":"date"
        ,"id":"date"
        ,"label":"Date"
    }
    ,{
        "type":"string"
        ,"id":"details"
        ,"label":"Details"
        ,"textarea": true
    }
    ]
}

Updating Schemas:
Once the definition.json files are updated with the new schema design structures, you can update the schemas in a number of ways. You can either update each schema individually or you can update all of the schemas at once.

Update a specific schema:

 e.g. ../nunaliit2-couch-sdk-2.2.6/bin/nunaliit update-schema --name testatlas_bank

Note: The name of the schema is typically the groupname_schemaid. If you are unsure of the name of the schema, you should consult the name.txt file within the schema’s directory

Update all schemas:

 e.g. ../nunaliit2-couch-sdk-2.2.6/bin/nunaliit update-schema --all

Updating the Atlas:

The update-schema tool updates each of the files in the schema directory with the newly defined schema’s structure. However these changes won’t be seen in the atlas until the atlas it’s self is updated.

 e.g. ../nunaliit2-couch-sdk-2.2.6/bin/nunaliit update

Following the update of the atlas, you should now be able to use these schemas in your atlas. See a screenshot of the schema form view below.

screenshotofschemadisplay

Nunaliit form view of the Bank schema

Customizing your schema:

Using the add-schema and update-schema tools allows for quick creation and updating of schema documents in Nunaliit. However, you are not limited to the use of these tools. You can edit the files in the schema directory, allowing an atlas builder to customize your schema’s design. Note: If you decided to customize a schema, you will likely want to delete your definition.json file from the schema directory to prevent your custom changes being overwritten accidentally with the nunaliit update-schema –all.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s