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 submitted contract-related data.
The following sections provide details that developers need to construct valid contracts. All data contracts must define one or more documents that conform to the general data contract constraints.
The documents object defines each type of document required by the data contract. At a minimum, a document must consist of 1 or more properties. Documents may also define indices and a list of required properties. The additionalProperties properties keyword must be included as described in the constraints section.
The following example shows a minimal documents object defining a single document (note) with one property (message).
{ "note": { "properties": { "message": { "type": "string", "position": 0 } }, "additionalProperties": false } }
The properties object defines each field that a document will use. Each field consists of an object that, at a minimum, must define its data type (string, number, integer, boolean, array, object) and a position.
Fields may also apply a variety of optional JSON Schema constraints related to the format, range, length, etc. of the data. A full explanation of JSON Schema capabilities is beyond the scope of this document. For more information regarding its data types and the constraints that can be applied, please refer to the JSON Schema reference documentation.
**Assigning property position**Each property in a level must be assigned a unique position
value, with ordering starting at zero and incrementing with each property. When using nested objects, position counting resets to zero for each level. This structure supports backward compatibility in data contracts by ensuring consistent ordering for serialization and deserialization processes.
Special requirements for object properties The object type cannot be an empty object but must have one or more defined properties. For example, the body property shown below is an object containing a single string property (objectProperty):
const contractDocuments = { message: { type: "object", properties: { body: { type: "object", position: 0, properties: { objectProperty: { type: "string", "position": 0 }, }, additionalProperties: false, }, header: { type: "string", "position": 1 } }, additionalProperties: false } };
There are a variety of constraints currently defined for performance and security reasons.
| Description | Value |
|---|---|
| Minimum number of properties | 1 |
| Maximum number of properties | 100 |
| Minimum property name length | 1 (Note: minimum length was 3 prior to v1.0.0) |
| Maximum property name length | 64 |
| Property name characters | Alphanumeric (A-Z, a-z, 0-9) |
Hyphen (-) |
|
Underscore (_) |
Prior to Hellar Platform v1.0.0 there were stricter limitations on minimum property name length and the characters that could be used in property names.
Each document may have some fields that are required for the document to be valid and other optional fields. Required fields are defined via the required array, which contains a list of the field names that must be present in the document. The required object should only be included for documents with at least one required property.
"required": [ "<field name a>", "<field name b>" ]