Domino AppDev Pack

1.0.0

domino-db Document Schema

The domino-db module represents a document as a JavaScript object. The exact structure of the object varies with the items on the document. In other words, the object structure is application specific. There are rules for converting each document item to JavaScript, but before we describe the rules, it's useful to start with an example.

domino-db documents by example

Let’s say you have a document representing contact information. The form name is "Contact", and the document includes the following TEXT items: FirstName, LastName, City, and State. When you use domino-db to read this document, you get an object like this:

  {
    '@unid': '4A51270A49D9C592852582DA0055D63F',
    '@created': {
      type: 'datetime',
      data: '2018-07-30T15:37:34.07Z'
    },
    '@modified': {
      type: 'datetime',
      data: '2018-07-30T15:37:35.09Z'
    },
    Form: 'Contact',
    FirstName: 'Edwin',
    LastName: 'Moody',
    City: 'Toledo',
    State: 'OH'
  }

The first thing you will notice is that some property names begin with "@". These are system properties. For example, the @unid property represents the UNID of the document, and @created represents the date the document was created. System properties represent document metadata. When you use domino-db to create or update a document, the system properties are ignored. In other words, you cannot assign or change a document UNID or created date. For more details, see System properties.

In the above example, the Form, FirstName, LastName, City, and State properties map directly to application-specific items on the document. Obviously these properties make sense for a contact document. You would get a different set of properties if you read another type of document. For example, an object representing a mail message would have properties named Subject, From, and SendTo -– just to name a few properties.

Item property schema

The canonical format for an item property is as follows:

  <item-name>: {
    type: <item-type>,
    data: <item-data>,
    nonsummary: <nonsummary-flag>,
    encrypt: <encrypt-flag>
  }

where:

  • <item-name> is the corresponding item name.
  • <item-type> is a string indicating the item type. Legal values include 'text', 'number', and 'datetime'. This version of domino-db doesn't include support for MIME, rich text and other "advanced" item types.
  • <item-data> is a string, number, or array representing the item data.
  • <nonsummary-flag> is a boolean value, true if the corresponding item does not contain summary data. When omitted the default value is false.
  • <encrypt-flag> is a boolean value, true if the item is encrypted. When omitted the default value is false.

For example, the following property represents a DATETIME item:

  Date: {
    type: 'datetime',
    data: '2013-03-01T14:09:01Z'
  }

And the following represents a DATETIME_LIST:

  Dates: {
    type: 'datetime',
    data: [
      '2013-03-01T14:00:00Z',
      '2013-03-02T15:00:00Z',
      '2013-03-03T16:00:00Z'
    ]
  }

If you want be rigorously consistent, you could represent a TEXT and TEXT_LIST item like this:

  Genus: {
    type: 'text',
    data: 'Panthera'
  },
  Species: {
    type: 'text',
    data: ['Lion', 'Tiger', 'Leopard']
  }

The above example is perfectly legal, but it can be simpler to imply the type of TEXT and TEXT_LIST items like this:

  Genus: 'Panthera',
  Species: ['Lion', 'Tiger', 'Leopard']

The previous two examples are functionally equivalent, but the second form is much simpler to use in practice. In other words, the simple format can be defined as:

  <item-name>: <item-data>

where:

  • <item-name> is the corresponding item name.
  • <item-data> is a string, number, or array representing the item data.
  • <item-type> is inferred from <item-data>.
  • <nonsummary-flag> is assumed to be false.
  • <encrypt-flag> is assumed to be false.

It's important to understand you can use this simple format only for 'text' and 'number' item types. It does not work for the 'datetime' type. Also, you cannot use the simple format for encrypted and nonsummary items.

NOTE: When you use the canonical format, the encrypt property corresponds to the item SEAL flag, and the nonsummary property is the inverse of the item SUMMARY flag. A document item may include several other flags including SIGN, NAMES and READERS. This version of domino-db does not include support for these other item flags.

Property examples by item type

TEXT

Simple format:

  Genus: 'Panthera',

Canonical format:

  Genus: {
    type: 'text',
    data: 'Panthera',
    encrypt: true
  }

  Description: {
    type: 'text',
    data: 'Some very large string',
    nonsummary: true
  }

TEXT_LIST

Simple format:

  Species: ['Lion', 'Tiger', 'Leopard'],

Canonical format:

  Species: {
    type: 'text',
    data: ['Lion', 'Tiger', 'Leopard'],
    encrypt: true
  }

DATETIME

Date and time:

  Datetime: {
    type: 'datetime',
    data: '2013-03-01T14:09:01Z'
  }

Date only:

  Date: {
    type: 'datetime',
    data: '2018-12-11'
  }

Time only:

  Time: {
    type: 'datetime',
    data: '15:30:00'
  }

NOTE: For more details on the way domino-db represents a DATETIME item, see Datetime values

DATETIME_LIST

  Dates: {
    type: 'datetime',
    data: [
      '2013-03-01T14:00:00Z',
      '2013-03-02T15:00:00Z',
      '2013-03-03T16:00:00Z'
    ]
  }

DATETIME_PAIRS

  DatePairs: {
    type: 'datetime',
    data: [
      ['2013-03-01T14:00:00Z', '2013-03-02T15:00:00Z'],
      ['2013-03-03T16:00:00Z', '2013-03-02T17:00:00Z']
    ]
  }

NUMBER

Simple format:

  Number: 999,

Canonical format:

  Number: {
    type: 'number',
    data: 999,
    nonsummary: true
  }

NUMBER_LIST

Simple format:

  Numbers: [997, 998, 999],

Canonical format:

  Numbers: {
    type: 'number',
    data: [997, 998, 999],
    nonsummary: true
  }

NUMBER_PAIRS

Simple format:

  NumberPairs: [[997, 998], [999, 1000]],

Canonical format:

  NumberPairs: {
    type: 'number',
    data: [
      [997, 998],
      [999, 1000]
    ],
    nonsummary: true
  }

Datetime values

You might wonder why domino-db doesn't simply use a JavaScript Date to represent a Domino DATETIME. The answer is you cannot reliably convert a DATETIME to a Date (and vice versa). There are at least three differences between the two types:

  • A Domino DATETIME is only precise to a hundredth of a second. A JavaScript Date is more precise -- to the millisecond.
  • A Domino DATETIME can contain a date only (no time).
  • A Domino DATETIME can contain a time only (no date).

Since you cannot reliably convert between the two types, domino-db represents each DATETIME value as a JavaScript object with a type of 'datetime' -- for example:

  // Date and time
  Datetime: {
    type: 'datetime',
    data: '2013-03-01T14:09:01.01Z'
  },
  // Date only
  Date: {
    type: 'datetime',
    data: '2018-12-11'
  },
  // Time only
  Time: {
    type: 'datetime',
    data: '15:30:00.01'
  }

Of course, there may be situations where your application needs to convert between a JavaScript Date and a Domino DATETIME. For example, let's assume you want to write a document item of type DATETIME where the value is equal to myDate (and myDate is an instance of Date). You might be tempted to use toISOString() like this:

  Datetime: {
    type: 'datetime',
    data: myDate.toISOString()
  },

Unfortunately, toISOString() writes a value with millisecond precision. Therefore, when you use Database.createDocument() to write a document containing the above item, the request will fail. You must format myDate to be no more precise than a hundredth of a second. In other words:

  '2013-03-01T14:09:01.009Z' // Invalid (too precise)
  '2013-03-01T14:09:01.01Z' // Valid

Usually, this means you will want to use an existing Node.js package to format and parse date values for use by domino-db. For example, moment is one good package for handling dates, but ultimately it is up to you to find the package that meets your needs.

HINT: If you are using moment, use the following format string for parsing and writing date values: 'YYYY-MM-DDTHH:mm:ss.SS[Z]'.

System properties

When you read a document, domino-db includes the following system properties. These properties are read-only. When you create or update a document, system properties are ignored.

@created

Description: When the document was originally created.

Type: datetime

Example

  '@created': {
    type: 'datetime',
    data: '2018-07-30T15:37:34.07Z'
  }

@modified

Description: When the document was last modified.

Type: datetime

Example

  '@modified': {
    type: 'datetime',
    data: '2018-07-30T15:37:35.09Z'
  }

@unid

Description: The document's universal ID. This ID is the same across all replicas of the database.

Type: string

Example

  '@unid': '4A51270A49D9C592852582DA0055D63F',
← domino-db Quick Startdomino-db Reference →