Data Collection#
A Data Collection is like a database table: it stores records with declared fields. For example, Supplier stores supplier records and PurchaseOrder stores purchase order records.
A Collection has a name and documentation explaining what its records represent, why the System stores them and how Processes use them. The System Design author defines the Collections needed by the business and the relationships between them.
The produced file is collections/<collection-name>.json; its filename uses the Collection's exact name. It follows Data-Collection.schema.json.
| Property | Meaning |
|---|---|
name |
Collection name, unique among Collections in this System and used in references and its filename. |
description |
Business meaning of the stored records. |
tags |
Optional list of distinct, nonblank labels chosen by the author for grouping, filtering and discovery. |
fields |
Record properties, their types, meanings and constraints. |
indexes |
Plain or unique indexes over one or several fields, optionally restricted by a condition. |
relationships |
Optional named relationships to other Collections, with required, optional or many cardinality. A many relationship does not imply automatic array-reference conversion or hydration. |
states |
Optional descriptions of business states, when the author uses them. Not every Collection needs states. |
Tags are general-purpose labels, not predefined categories. For example, "tags": ["Purchasing", "Supplier Management"]. Omit tags or use an empty array when no labels are needed. Tags belong to the Collection definition, not its records. They do not change storage, grant access or establish certification.
Fields#
Fields describe the information held by each record. Each field has a name, a label, a description and a type. The name is used in code and references; the label is readable display text, such as merchantReference and Merchant Reference. A field can also define whether a value is required, a default value, allowed values and other constraints supported by its type.
Use values for a fixed list of allowed values chosen by the System author. Each value follows the field's type. Omit values when there is no fixed list. The field's label is its display name, not a label for each choice.
The available field types are:
string: a character value, with a length when needed.text: longer textual content.integerandlong: whole numbers.decimal: numbers with a fractional part, such as amounts or rates. Use AIScript decimal calculations and explicit rounding where the business rule requires it.boolean: a true or false value.date: a calendar date.datetime: a date and time.object: a structured value whose properties are described by a nested schema.array: several stored values.sTypedefines the element type and defaults tostringwhen omitted. Structured elements have a nested schema. An array does not provide the record-reference behavior described below.reference: a relationship to a record in another Collection, identified bycollection.file: stored metadata describing a file:id(upload identifier),name,contentType,extensionandsizein bytes. It stores neither the contents nor a filesystem object. Several files can be stored in an array with a schema describing these metadata objects.
Field descriptions explain business meaning, not just repeat the field name. For example, an amount description states what the amount represents and which currency applies. A status field describes its values and their meaning. The author chooses these business fields and rules.
Record ID And Required Fields#
Every Collection requires these fields:
id: identifies a stored record, like a database row ID. Its type isstringorinteger. Prefer automatic generation: a generated string ID is 24 characters long, while an integer ID uses an auto-incrementing sequence. A supplied ID is also supported when needed.timestamp: adatetimefield with the current date and time as its default value.deleted: abooleanfield withfalseas its default value.
Relationships#
Collections reference each other to express relationships between records. A reference names the target Collection and represents a related record, not a copy of that record's fields.
For example, PurchaseOrder can have a supplier reference to Supplier. Several purchase orders can reference the same supplier. A Process can use that relationship to retrieve the supplier associated with an order.
Name a reference field after the related object, such as supplier, rather than supplierId. Use a required reference when the related record must exist and an optional reference when it may be absent.
An embedded object belongs to its containing record. A reference points to a separately stored record with its own identity. The author decides which representation matches the business relationship.
Arrays Of Record IDs#
An array of record IDs is not equivalent to a reference field. In the native Collection specification, an array can name another Collection as its sType; this determines the database array's element type from that Collection's id type. The stored elements are IDs, not related record objects.
Process code must supply the ID values, not an array of Record handles. The database Service does not convert those handles into IDs, automatically load the related records, or enforce a foreign key for each array element. A Process retrieves related records explicitly when it needs them.
To represent several related records using ordinary references, a separate Collection can hold the relationships, with each record referencing the records it connects. The author chooses the representation needed by the business.
Indexes And Uniqueness#
Indexes support the searches performed by Processes. An index can cover one field or several fields together. A plain index supports lookup; a unique index also prevents duplicate values for its indexed fields. A partial index applies only to records matching its condition, such as deleted = false.
For example, a unique index on an order number can enforce its business uniqueness. A combined index on supplier and timestamp can support listing a supplier's orders by time. Indexes must correspond to actual fields and the queries that use them.
An index uses type, fields and optional where. Use type: "plain" or type: "unique"; uniqueness is not a separate boolean property. For example, this item in a Collection's indexes list makes active supplier codes unique:
{
"type": "unique",
"fields": ["code"],
"where": { "deleted": false }
}
Soft Deletion#
Records are never physically deleted. A Process deletes a record by updating deleted to true. Normal queries filter on deleted = false. Retrieving deleted records is an explicit operation.
Soft deletion preserves the record's identity and stored information. It does not erase references from other records. Processes must account for whether related records are active or deleted when applying business rules.
Collections And Processes#
Collections describe stored information; Processes describe the actions that read or change it through a database Service. Their definitions must agree: a Process uses the declared fields, follows the declared relationships and stores the information needed to produce its promised result.
The Data Collection specification is Data-Collection.schema.json.
JSON Example#
{
"name": "Supplier",
"description": "Suppliers from whom the business purchases goods or services.",
"fields": [
{
"name": "id",
"description": "Supplier record identity.",
"type": "string",
"length": 24,
"auto": true,
"key": true,
"label": "ID"
},
{
"name": "timestamp",
"description": "Time the record was created.",
"type": "datetime",
"default": "now",
"label": "Timestamp"
},
{
"name": "deleted",
"description": "Whether the supplier record is soft-deleted.",
"type": "boolean",
"default": false,
"label": "Deleted"
},
{
"name": "name",
"description": "Supplier's business name.",
"type": "string",
"required": true,
"length": 160,
"label": "Name"
}
]
}
The example demonstrates structure, not a prescribed set of business fields. Record-reference fields use type: "reference" and the target Collection's exact name in collection. Process dependencies also use the Collection's exact name. Stored records are selected using their record id values.
An individual field with allowed values:
{
"name": "status",
"label": "Status",
"description": "Current business state of the record.",
"type": "string",
"values": ["pending", "approved", "rejected"]
}