# 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/.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. - `integer` and `long`: 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. `sType` defines the element type and defaults to `string` when 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 by `collection`. - `file`: stored metadata describing a file: `id` (upload identifier), `name`, `contentType`, `extension` and `size` in 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 is `string` or `integer`. 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`: a `datetime` field with the current date and time as its default value. - `deleted`: a `boolean` field with `false` as 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: ```json { "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 ```json { "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: ```json { "name": "status", "label": "Status", "description": "Current business state of the record.", "type": "string", "values": ["pending", "approved", "rejected"] } ```