In this scenario, a data set refers to a type of data structure. It might be a basic structure with a single level of fields, or it could be a more complex object that encompasses collections of data and various sub-objects.

Datasets are specified as root level properties within the schema. Multiple datasets can be defined, as a single screen may need to display various types of data.

{
    "datasets": [
        {
            "id": "person",
            "fields": [
                { "name": "firstName" }
                { "name": "lastName" }
                { "name": "age" }
            ]
        }
    ],
    
    "body": { ... }
}

Fields can have two standard additional properties attached to them, each influencing their behavior in specific ways.

1. default: This attribute assigns a predetermined value to a field for every new instance of the data structure, ensuring a consistent starting point.
2. ignore-dirty-check: Activating this setting results in modifications to the field being omitted from all state change assessments. Essentially, any changes made to this field remain hidden from the system’s overall monitoring process. Typically, when a field in the dataset undergoes modification, the model is marked as ‘dirty’, tracking both the original and the updated values. This ‘dirty’ status signals that there are modifications intended for saving, activating mechanisms that allow these changes to be stored permanently. However, opting to bypass the ‘dirty check’ means instructing the system not to mark the model as ‘dirty’ in response to changes, effectively ignoring any updates to this model since they won’t be saved to the storage.

{
    "datasets": [
        {
            "id": "person",
            "fields": [
                { 
                    "name": "firstName",
                    "default": "John"
                },
                {
                    "name": "isSelected",
                    "default": false,
                    "ignore-dirty-check": true
                }
            ]
        }
    ],
    
    "body": { ... }
}

Data source as a field

In certain cases, a field may need to function as a collection of records. To achieve this, the field must be designated as a collection and linked to a specific data source definition that outlines the method for retrieving these records. It’s important to note that when such a field is associated with a component, its data is only fetched when the component is activated.

{
    "datasources": [
        {
            "id": "children_datasource",
            ...
        }
    ],

    "datasets": [
        {
            "id": "person",
            "fields": [
                { 
                    "name": "firstName",
                    "default": "John"
                },
                {
                    "name": "children",
                    "collection": true,
                    "datasource": "children_datasource"                   
                }
            ]
        }
    ],
    
    "body": { ... }
}

Data set actions

Data sets, much like data sources, can be connected to an intent definition, allowing for various specific actions to be executed on the data.

primaryActions

• load: This action involves retrieving data from the server for the data set and filling the data structure with the retrieved information.
• update: This involves syncing changes made in the local data model with the server version of the data model.
• create: If the data model isn’t already present on the server, this action allows for its creation using the values defined in the local data structure.

{
    "datasets": [
        {
            "id": "person",
            "fields": [
                { 
                    "name": "firstName",
                    "default": "John"
                }
                ...
                
            ],
            "primaryActions": {
                "load": {
                  "remote": "Person",
                  "action": "GetPerson",
                  "parameters": {
                    "Person->Id": "@parameters.personId"
                  }
                },
                
                "create": {
                  "remote": "Person",
                  "action": "CreatePerson"
                },
                
                "update": {
                  "remote": "Person",
                  "action": "UpdatePerson",
                  "parameters": {
                    "Person->Id": "@parameters.personId"
                  }
                }            
            }
        }
    ],
    
    "body": { ... }
}

From the above example, it’s evident that the primary actions for the data set mirror those of the data source. In every scenario, the following needs to be defined:

1. remote: Specifies the remote entity on the server where the action will be executed.
2. action: Defines the remote action to carry out the intended operation.
3. parameters: Details any parameters needed for the server action, if applicable.

Preview settings

The concept of preview screens is not to replicate the create or edit screens. Instead, a preview screen is designed to provide a concise summary, highlighting the most crucial information about a specific entity.

In the context of relational data, a field within the dataset may signify a relationship with a different entity, which is indicated through a reference.

Behind the scenes, a lookup table is in place to determine the available preview screens. When a user opts to preview the record linked to a field value, this lookup table is consulted. The schema for that particular screen is then retrieved and displayed in an isolated environment, essentially creating a sandbox for that specific preview.

{
    "datasets": [
        {
            "id": "person",
            "fields": [
                { 
                  "name": "firstName",
                  "preview": "person_preview"
                }
            ]
        }
    ],
    
    "body": { ... }
}

Looking at the mapping JSON file, the previews are defined in a root property called “previews”

{
    "previews": [
      {
          "id": "my_preview",
          "remote": "asset",
          "lookup-field": "id",
          "dataset-field": "assetId"
        },    
    ]
}

In the above preview you have to define:

1. id: This is the unique identifier for the preview definition.
2. remote: This refers to the name of the entity, which is crucial for locating the appropriate preview schema for that entity. While an entity may have various profiles, it typically has only one preview screen. The entity name is essential for identifying and loading the correct schema for display.
3. lookup-field: This field name determines the specific field used for loading a record. For example, in the given scenario, “id” is designated as the lookup field. This means that the record will be identified by matching its ‘id’ with the value provided from the dataset field. Essentially, it operates on a principle like, “Find the asset where the id matches the “assetId” field from my current dataset.”
4. dataset-field: In the dataset definition that triggers the preview, this field is used as the value in the lookup-field. It helps in pinpointing the correct record to display on the preview screen.

Lookup settings

In scenarios involving referential relationships, a lookup process is initiated during data capture. This involves displaying a screen with a list of eligible records for selection, relevant to the record currently being captured. The details for this lookup are not contained within the current schema; instead, they are part of a separate entity lookup definition. On the dataset field, it’s necessary to specify which lookup from the lookup schema should be executed during this process.

{
    "datasets": [
        {
            "id": "person",
            "fields": [
                { 
                  "name": "firstName",
                  "lookup": "person_lookup"
                }
            ]
        }
    ],
    
    "body": { ... }
}

In the lookup definition file, the various lookups are specified within a property named “lookup-registry”.

{
    "lookup-registry": [
        "my_lookup": {
            "template": "MyLookupSchemaTemplateName"
        },    
    ]
}

The provided text describes a straightforward lookup table design. The table uses unique IDs as keys. Each key is associated with a value, which is an object containing a ‘template’ property. This ‘template’ property specifies the schema necessary for loading and displaying records on the lookup screen. The design is intentionally object-based to allow for extensibility. Additional markup can be incorporated if needed, but for most purposes, the ‘template’ property alone suffices.