Data contracts define the schema (structure) of data an application will store on Hellar Platform. Contracts are described using JSON Schema which allows the platform to validate the contract-related data submitted to it.
The following sections provide details that developers need to construct valid contracts: documents and definitions. All data contracts must define one or more documents, whereas definitions are optional and may not be used for simple contracts.
There are a variety of constraints currently defined for performance and security reasons. The following constraints are applicable to all aspects of data contracts. Unless otherwise noted, these constraints are defined in the platform’s JSON Schema rules (e.g. rs-hpp data contract meta schema).
Keyword
🚧
The
$refkeyword has been disabled since Platform v1.0.0
| Keyword | Constraint |
|---|---|
default |
Restricted - cannot be used (defined in HPP logic) |
propertyNames |
Restricted - cannot be used (defined in HPP logic) |
uniqueItems: true |
maxItems must be defined (maximum: 100000) |
pattern: <something> |
maxLength must be defined (maximum: 50000) |
format: <something> |
maxLength must be defined (maximum: 50000) |
$ref: <something> |
Temporarily disabled |
$ref can only reference $defs - |
|
| remote references not supported | |
if, then, else, allOf, anyOf, oneOf, not |
Disabled for data contracts |
dependencies |
Not supported. Use dependentRequired and dependentSchema instead |
additionalItems |
Not supported. Use items: false and prefixItems instead |
patternProperties |
Restricted - cannot be used for data contracts |
pattern |
Accept only RE2 compatible regular expressions (defined in HPP logic) |
Note: These constraints are defined in the Hellar Platform Protocol logic (not in JSON Schema).
All serialized data (including state transitions) is limited to a maximum size of 16 KB.
Although JSON Schema allows additional, undefined properties by default, they are not allowed in Hellar Platform data contracts. Data contract validation will fail if they are not explicitly forbidden using the additionalProperties keyword anywhere properties are defined (including within document properties of type object). Include the following at the same level as the properties keyword to ensure proper validation:
"additionalProperties": false
The data contract object consists of the following fields as defined in the JavaScript reference client (rs-hpp):
| Property | Type | Required | Description |
|---|---|---|---|
| protocolVersion | integer | Yes | The platform protocol version (currently 1) |
| $schema | string | Yes | A valid URL (default: https://schema.hellar.org/hpp-0-4-0/meta/data-contract) |
| $id | array of bytes | Yes | Contract ID generated from ownerId and entropy (32 bytes; content media type: application/x.hellar.hpp.identifier) |
| version | integer | Yes | The data contract version |
| ownerId | array of bytes | Yes | Identity that registered the data contract defining the document (32 bytes; content media type: application/x.hellar.hpp.identifier |
| documents | object | Yes | Document definitions (see Documents for details) |
| $defs | object | No | Definitions for $ref references used in the documents object (if present, must be a non-empty object with <= 100 valid properties) |
Details regarding the data contract object may be found in the rs-hpp data contract meta schema. A truncated version is shown below for reference:
{ "$schema": "<https://json-schema.org/draft/2020-12/schema>", "$id": "<https://schema.hellar.io/hpp-0-4-0/meta/data-contract>", "type": "object", "$defs": { // Truncated ... }, "properties": { "protocolVersion": { "type": "integer", "minimum": 0, "$comment": "Maximum is the latest protocol version" }, "$schema": { "type": "string", "const": "<https://schema.hellar.io/hpp-0-4-0/meta/data-contract>" }, "$id": { "type": "array", "byteArray": true, "minItems": 32, "maxItems": 32, "contentMediaType": "application/x.hellar.hpp.identifier" }, "version": { "type": "integer", "minimum": 1 }, "ownerId": { "type": "array", "byteArray": true, "minItems": 32, "maxItems": 32, "contentMediaType": "application/x.hellar.hpp.identifier" }, "documents": { "type": "object", "propertyNames": { "pattern": "^[a-zA-Z0-9-_]{1,64}$" }, "additionalProperties": { "type": "object", "allOf": [ { "properties": { "indices": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32 }, "properties": { "type": "array", "items": { "type": "object", "propertyNames": { "maxLength": 256 }, "additionalProperties": { "type": "string", "enum": [ "asc" ] }, "minProperties": 1, "maxProperties": 1 }, "minItems": 1, "maxItems": 10 }, "unique": { "type": "boolean" } }, "required": [ "properties", "name" ], "additionalProperties": false }, "minItems": 1, "maxItems": 10 }, "type": { "const": "object" }, "signatureSecurityLevelRequirement": { "type": "integer", "enum": [ 0, 1, 2, 3 ], "description": "Public key security level. 0 - Master, 1 - Critical, 2 - High, 3 - Medium. If none specified, High level is used" } } }, { "$ref": "#/$defs/documentSchema" } ], "unevaluatedProperties": false }, "minProperties": 1, "maxProperties": 100 }, "$defs": { "$ref": "#/$defs/documentProperties" } }, "required": [ "protocolVersion", "$schema", "$id", "version", "ownerId", "documents" ], "additionalProperties": false }