System Properties

Every document carries a few values the platform manages rather than the writer: its id, its owner, and, on some types, its revision, its creator, the times it was created, updated and transferred, and who last moderated it and when. Their names start with $. A document type does not declare them in properties. It names them where it wants to use them: in required, to have a timestamp recorded, in indices, to query by them, and in the keywords that accept one, such as a reference's propertyAgreement.

Example

"listing": {
  "type": "object",
  "documentsMutable": true,
  "transferable": 1,
  "tradeMode": 1,
  "indices": [
    { "name": "byCreator", "properties": [{ "$creatorId": "asc" }, { "$createdAt": "asc" }] },
    { "name": "byOwner", "properties": [{ "$ownerId": "asc" }, { "$updatedAt": "asc" }] }
  ],
  "properties": {
    "title": { "type": "string", "minLength": 1, "maxLength": 100, "position": 0 }
  },
  "required": ["$createdAt", "$updatedAt", "$transferredAt", "title"],
  "additionalProperties": false
}

Every listing records when it was created, last updated and last transferred, because required lists the three times. Listings can be replaced, transferred and sold, so each one also carries a revision and the id of its creator, and the two indexes find them by who made them and by who holds them now.

$id

A document's id is derived from the contract id, the owner's id, the document type's name, entropy chosen by the client and, from protocol version 14, the identity contract nonce of the create transition. Consensus derives it again for every create and refuses a transition that carries another. The id never changes. See Document ID Generation.

Documents are already stored by id, so an index may not name $id. A reference's propertyAgreement may name it on the referenced side (see References).

$ownerId

The owner is the identity that created the document, until a transfer or a purchase hands it to another. Only the owner may replace, transfer, reprice or delete it with a document transition. A document can also leave by other paths, a moderators' deletion or an expired ttl; see Deletion.

$ownerId may be indexed, and several keywords read it, where it usually stands for the writer of the document:

• distinctFrom: "$ownerId" makes a property differ from the owner.
• propertyConstraints: a rule may compare an identifier property with $ownerId.
• References: a propertyAgreement pair, a lookup key and identityProperty may name it, and ownerRefersTo checks the owner itself.
• encryptedFor: "recipient": "$ownerId" marks a message the writer encrypts to themself.

$revision

A new document has revision 1. Every replace, transfer, price update and purchase raises it by one, and the transition must state the new revision: the stored revision plus one. A transition built against an older copy of the document is refused, rather than silently overwriting a newer one. A moderator's change of the fields a type keeps for its moderators raises it by one too; the moderation transition states no revision, the platform sets it, and an owner's replace built before the change is refused. A type whose documents can never change after creation carries no revision. $revision is not one of the system properties an index may name.

Timestamps

The platform sets these from the block that processes the transition; the writer never supplies them. A timestamp that is not in required is never recorded, and documents of the type do not have it.

Timestamps may be indexed. Some keywords need one in required, since they read it:

• ttl counts from $createdAt.
• moderatorAbilities.deleteWithin counts from $updatedAt, or from $createdAt on a type that does not record $updatedAt (see Deletion).
• A time-range index needs the timestamp it buckets.

Block heights

The same three events as the timestamps, measured in blocks instead of time. Each is set on the same events as the timestamp of its name, and may be indexed.

$creatorId

On a type whose documents can change hands, $ownerId follows the document while $creatorId stays with the identity that created it: a transfer or a purchase never changes it. On a type whose documents never change hands the creator is always the owner, and no $creatorId is recorded. Neither is it on a contract of format 0 or with a config of version 0, whatever its types allow.

$creatorId is not written in required or properties. It may be named:

• in an index;
• on the referenced side of a reference's propertyAgreement, and as a key reference's identityProperty;
• by creatorRefersTo, which checks the creator. A type that does not record creators may not declare it (InvalidContractStructure, 10231).

$moderatedAt and $moderatedBy

The two record the last time a moderator wrote the fields only moderators write, and who did. They are set together, from the block that processes the write, and never by the writer:

Nothing else moves them: a replace that leaves those fields as they were, a transfer, a purchase and a price update keep them, and a restore puts them back as they were. They do not change $updatedAt, which stays the owner's. A document no moderator has written carries neither, and a type that keeps no fields for its moderators never records them.

Both may be indexed, on a type that lists changeFields, so an application can find what its moderators handled, by whom and in what order:

"indices": [
  { "name": "byModerator", "properties": [{ "$moderatedBy": "asc" }, { "$moderatedAt": "asc" }] }
]

A unique index may not name them: a moderator's change would be refused because another document holds the same stamp. They are not written in required or properties, and no other keyword reads them.

See also

• What Lives Inside a Document, for the fields of a document
• Document Shape, for the required list that records timestamps
• Document Serialization, for where each system property sits in the stored bytes
• Creation, Transfers and Trading, for the flags that decide $revision and $creatorId
• Moderator Abilities, for the fields whose writes $moderatedAt and $moderatedBy record