Contract-Level Keys and config

The document types sit inside a data contract, which has keys of its own: its id, its owner, its version, the shared definitions its types may point at, its tokens and groups, and a search description. One of them, config, holds contract-wide settings: whether the contract can ever change, whether it keeps its history, the defaults its document types inherit, how integers are stored, and whether and how it is moderated. Almost every config setting is chosen once, at registration, and kept for the contract's life.

Example

{
  "$formatVersion": "1",
  "id": "AY6xWncZUFv2GCrS5seqKthUfbW9yYyUXtF8diSuHQ4g",
  "ownerId": "AtirhSVpAWF7dEt6dLAmesC4Sr1MsJ9bFC1nLAoNnq2S",
  "version": 1,
  "config": {
    "$formatVersion": "2",
    "canBeDeleted": false,
    "readonly": false,
    "keepsHistory": false,
    "documentsKeepHistoryContractDefault": false,
    "documentsMutableContractDefault": true,
    "documentsCanBeDeletedContractDefault": true,
    "sizedIntegerTypes": true,
    "moderation": {
      "banlist": true,
      "suspensions": true,
      "moderators": { "$type": "contractOwner" }
    }
  },
  "documentSchemas": {
    "post": {
      "type": "object",
      "properties": {
        "text": { "type": "string", "minLength": 1, "maxLength": 280, "position": 0 }
      },
      "required": ["text"],
      "additionalProperties": false
    }
  },
  "keywords": ["social", "microblog"],
  "description": "Short public posts"
}

A first version of a small social contract. Its config states the defaults explicitly, stores integers in the smallest width their bounds allow, and keeps a banlist and a suspension list that the owner edits. keywords and description make it findable through the keyword search contract.

Contract keys

documentSchemas

A contract has at least one document type, unless it defines tokens (DocumentTypesAreMissingError, 10214). A name is 1 to 64 ASCII letters, digits, _ or -; from protocol version 14 a name may not contain - (InvalidDocumentTypeNameError, 10415). The keywords a schema takes are the subject of the rest of this part: see Contract Keywords.

keywords and description

The keyword search system contract indexes each contract by its keywords and description, so applications can find contracts by topic. The rules, checked on every create and update:

• At most 50 keywords (10262).
• Each keyword is 3 to 50 bytes of UTF-8 (10270) and contains no whitespace or control character (10269).
• No keyword appears twice (10263).
• A description is 3 to 100 bytes of UTF-8 (10264).

config

$formatVersion is the config's own version: "0" before protocol version 9, "1" from 9, and "2" from 14, which adds moderation. From protocol version 14 every new contract carries config version 2, moderated or not, and an older contract moves to it with its next update.

canBeDeleted

Whether the contract itself may ever be deleted. No transition deletes a contract today, so the flag has no effect yet beyond being recorded.

readonly

true freezes the contract at its first version: every update of it is refused with DataContractIsReadonlyError (40001). Only a create can set it, so a contract is read-only from the start or never. A document reference can require its target contract to be read-only (contractRequirements.readonly, see References).

keepsHistory

true makes Drive keep every version of the contract, not only the latest, so a client can read and prove the contract as it was at an earlier version.

Document type defaults

The value of documentsKeepHistory, documentsMutable and canBeDeleted for each document type that does not set it itself. A type that sets the keyword overrides the default. Changing a default would change every type that relies on it, so all three are fixed. See History, Mutability and Deletion.

Bounded key requirements

Let identities add encryption, or decryption, keys bound to the whole contract, and say how they are kept: one key that cannot be replaced, several, or several with a pointer to the latest. The document type keywords of the same names do this for keys bound to one document type. See Signing and Keys and Contract Bounds.

sizedIntegerTypes

With true, each integer property is stored in the smallest width its minimum, maximum or enum allow: "minimum": 0, "maximum": 100 takes one byte. With false, every integer is a signed 8-byte value. Turning it off would make stored documents unreadable, so it is refused. Turning it on is allowed by the config check, but it changes the width of every bounded integer of the existing document types, and an update that changes how an existing property's values are stored is refused (DocumentTypeUpdateError, 40212); in practice it can only be turned on when it leaves the width of every existing integer property unchanged.

The width also decides what a summed property may be: see Counts, Sums and Averages.

moderation

Declares which moderation lists the contract keeps and who edits them. An identity on the banlist, or suspended, cannot act on the contract's documents; a warning is a record that bars nothing. moderators is one of:

• { "$type": "contractOwner" }: the owner moderates alone.
• { "$type": "appointedModerators", "identities": [...] }: the owner and 1 to 16 named identities, each acting alone. Every named identity must exist (ContractModeratorIdentityNotFoundError, 41110).
• { "$type": "elected", ... }: a team elected by masternodes moderates, with the abilities the declaration gives it. See Elected Moderation.

A declaration keeps at least one list, unless a document type gives its moderators an ability (moderatorAbilities: deleting its documents or writing the fields it keeps for them), and is refused otherwise (InvalidContractModerationConfigError, 10900). An unknown key is refused rather than ignored, so a misspelled list name cannot silently leave the contract without it. Because the lists are fixed, a contract that will ever need moderation declares it when it is created.

moderation is what moderatorAbilities and the moderators' share of actionFees require.

See also

• Data Contracts for the contract structure and its versions.
• Contract Moderation for the lists, the moderation transition and elected teams.
• Contract Groups for contract groups, sets of contracts, which a create transition may register or join (not the contract's groups).
• Contract Keywords for the document type keywords.