Contract Keywords

A data contract describes its documents with a JSON schema per document type, and Platform reads a set of keywords in those schemas: some from JSON Schema, most of its own. The chapters of this part take each keyword, or a small group that works together, and say what it does, how to write it, what is checked when a contract is registered and when a document is written, what a later contract update may do with it, and which errors it produces. The chapters of the Data Model and Drive parts explain the internals behind them and are linked from each chapter.

Everything here follows the document meta-schema of protocol version 14, packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json. Every document type schema is validated against it when a contract is registered or updated, and the parser (try_from_schema) checks the rules a JSON schema cannot express. When a chapter and the meta-schema disagree, the meta-schema is right and the chapter is out of date.

Where keywords go

A contract's documentSchemas maps each document type name to its schema. Keywords sit at three levels:

"post": {
  "type": "object",
  "documentsMutable": true,
  "canBeDeleted": true,
  "indices": [
    { "name": "byOwner", "properties": [{ "$ownerId": "asc" }, { "$createdAt": "asc" }] }
  ],
  "properties": {
    "text": { "type": "string", "maxLength": 280, "maxBytes": 560, "position": 0 },
    "replyTo": {
      "type": "array", "byteArray": true, "minItems": 32, "maxItems": 32,
      "contentMediaType": "application/x.dash.dpp.identifier",
      "refersTo": { "type": "deletableDocument", "documentType": "post" },
      "position": 1
    }
  },
  "required": ["$createdAt", "text"],
  "additionalProperties": false
}

• Document type keywords sit at the top of the schema (documentsMutable, canBeDeleted, indices, required). They say what may happen to a document of the type and who may do it.
• Index keywords sit inside an entry of indices (name, properties).
• Property keywords sit inside a property's schema (type, maxLength, maxBytes, position, refersTo). Most are ordinary JSON Schema; the rest are Platform's own.

The contract around the document types has keys of its own, and a config object: see Contract-Level Keys and config.

Reading the chapters

Each chapter opens with a short table for each keyword:

• Since is the first protocol version at which the keyword can be used.
• On update is what a contract update may do with the keyword on a document type that already exists. Fixed means adding, removing and changing it are all refused. A document type the update adds may use any keyword, as a new contract may.
• Errors are consensus errors, written ErrorName (code). See Error Codes for the code ranges.

A contract update that breaks an update rule is refused with one of two errors, depending on which check catches it. DocumentTypeUpdateError (40212) comes from the comparison of the parsed document types, which judges flags such as documentsMutable by their meaning. IncompatibleDocumentTypeSchemaError (10246) comes from the comparison of the two JSON schemas, which judges property keywords such as refersTo or maxLength by their text. Top-level required and indices have errors of their own (10276 and 10217). Because the schema comparison reads text, an edit that changes how a keyword is written but not what it means, such as writing out a default or switching to the documentsAverageable shorthand, is refused with 10246.

Protocol versions

The document meta-schema has changed three times:

Most keywords of v0 took effect at protocol version 1. The exceptions are tokenCost (9) and the index keyword countable (12).

The complete language

Every key a contract can write, grouped by where it goes. Since is the protocol version from which the key works. Read more links to the key's section in this part and, where there is one, to the chapter with the internals. A dotted name such as tokenCost.<action>.amount is a key written inside the ones before it.

The contract

config

Document type

Property

A typed array's element (items) takes type, enum, minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, minLength, maxLength, pattern, format, minItems and maxItems (bytes of a byte array element), byteArray, contentMediaType, maxBytes, distinctFrom, refersTo, $comment and description. It takes no position, const, uniqueItems or examples.

refersTo

tokenCost and actionFees

<action> is one of create, replace, delete, transfer, update_price and purchase.

propertyConstraints

A rule is one condition. Conditions:

Expressions:

Index

System properties

Limits

The first three limits come from the meta-schema, the rest from protocol version 14's SystemLimits. A contract over a limit is refused at registration.