Last modified: Nov 10, 2024

Altinn Studio Data Modeling

Data model and Altinn Studio Data Modeling tool

Data models

Data Model Files for Applications

Data models for applications are located in the same folder structure as the rest of the application files. These are stored in the Altinn Studio repository under App/models in the application’s file structure. An application has 4 model files:

  • C# data model (<model>.cs): Data model used by the application’s backend/APIs to process and validate data.
  • JSON schema (<model>.schema.json): Data model in JSON schema format used by the application on the client-side (frontend) to validate data in real-time. This is also the file that is worked on in the data modeling tool.
  • XSD data model (<model>.XSD): Data model in XML format that defines the elements that can be used in a document. This is not directly used by the application but can be uploaded to generate the other model files in Altinn Studio or downloaded as needed.
  • JSON metadata (<model>.metadata.json): Used by Altinn Studio to generate the <model>.cs file. In the future, this file will not be stored in the application and will only be generated if needed.

Data models for organizations

Data models for organizations are located in Altinn Studio’s repos. To access these, log in with an Altinn Studio user. If this is your first time using Altinn Studio, you need to create a user.

The data models are located in the <org>-datamodels repository, where <org> is the organization you belong to. For example, the data models for the organization ‘Test Department (ttd)’ are located under https://altinn.studio/repos/ttd/ttd-datamodels.

You can find the link to this repository in the Altinn Studio Dashboard: https://altinn.studio/dashboard. Select Edit (blue pen icon) to access the Altinn Studio Data Modeling tool. Select Gitea (green cup icon) to view the files directly in the repository.

Overview of data model repo
Overview of data model repo

Access to Data Models

By default, anyone can view an organization’s data models. To gain access to edit the data models, the user needs to be part of the Data models team in the organization. Refer to the access management for more information.

Uploading XSD to Repository

XSD files can be directly uploaded to the tool Altinn Studio Datamodellering and are described under Upload and Display Data Model.

If you only need to upload XSD files for storage and do not intend to use the tool to edit the model, you can upload XSD files directly to the <org>-datamodels repo. To do this, navigate to the desired folder and select “Add file” -> “Upload file.” In the text field that appears at the top, you can enter the folder name you wish to use (optional). Upload the desired file, scroll down, optionally provide a message indicating the file type, and click “commit changes” to confirm.

Upload XSD directly to <org>-datamodels repo
Upload XSD directly to `<org>-datamodels` repo

Altinn Studio Data Modeling

The Data Modeling tool in Altinn Studio is under development and will have limited functionality until it is completed.

Altinn Studio Data Modeling is a tool for developing data models. It is based on a data model in JSONSchema format from which it can generate XSD and C# models (see Data Model Files for Applications).

  1. Log in to Altinn Studio. If you are not in the Altinn Studio Dashboard, navigate there by clicking on the logo in the top left corner or here.
  2. Select Edit (blue pen icon) either for:
    a. An app under “Mine applikasjoner” (My Applications) or
    b. Data Modeling repository for your organization.
  3. Select the Datamodell (Data model) tab in the top menu.

Upload and Display Data Model

The data model defines the data that can be submitted through an app and the allowed format of the data. Currently, we only support uploading XSD data models. When uploading an XSD model <model>.xsd, the tool will generate the following files: <model>.cs, <model>.schema.json, and <model>.metadata.json (see Data Model Files).

Depending on the XSD schema, the Studio generator will output decimal properties for the C# classes. decimal is a 128bit floating point number that is not fully representable in the JavaScript (JS) frontend of an Altinn app. If you use calculations to fill decimal property values you may end up using enough precision that some decimal digits are lost when deserialized in JS. In this case you will not be able to update the property from the frontend. If you calculate values with decimal precision, you should make sure the end result fits into double/64bit precision. Example:

dataModel.Result = (decimal)(double)(3.33m / 3.333m);

In the future we will improve data model generation to mitigate this.

  1. Click Last opp datamodell (Upload Data Model) from the homepage if there are no existing data models or Last opp (Upload) from the toolbar at the top of the tool.
  2. Select an XSD data model file in the file picker and click Last opp.

Upload Data Model
Upload Data Model

After the data model is processed, you can find the generated files under App/models/ in the app repository.

The types defined in the data model are displayed in the left-side panel. A tree view of the data model can be opened to see a visual representation of the data model and the available fields.

View Data Model
View Data Model

Selecting a Model from the Dropdown List

All models uploaded in the tool for an app or the organization’s repository (<org>-datamodels) are available from the drop-down list in the toolbar. XSDs that exist in a repository but do not have any associated model files (JSONSchema) will also appear in the list. See the next section for more information.

Specific to Organization-Level Data Modeling

When working with a data model repository at the organization level (instead of directly with an app), there are two groups of data models displayed in the dropdown list.

  • The first one is JSONSchema. These are models generated after the processing of uploaded XSD models.
  • The second one is XSD. These are the XSDs that exist in the <org>-datamodels repository but have not been imported and processed in the tool. When selecting a model from the XSD list, it will automatically be imported into the tool, and a JSONSchema model file will be generated. This can then be further worked on in Altinn Studio Designer.

Create a New Data Model

To create a new data model from scratch:

  1. Click Lag ny (Create new) on the left-side of the toolbar.
  2. Enter the name of the data model in the field.
  3. Click Opprett modell (Create model).

Create new data model
Create a new data model

The data model will be created with some example fields that you can work with or delete:

  • property1 (text, required)
  • property2 (text, required)
  • property3 (text)

New data model
New data model

Editing a Data Model

Functionality for editing the data model with the Altinn Studio Data Model tool is under development and will be somewhat limited until it is completed.

Select a model from the dropdown list on the toolbar and click Rediger (edit) in the top right corner of the model tool. A panel for editing the model will appear on the right side.

Edit data model
Edit data model

The JSON schema model is automatically saved as you work on it. To generate other model files such as XSD (and C# file for apps), you need to click Generer modeller (Generate Models) on the toolbar (see Generating Model Files).

Add New Field

To add a field at the top-level (root node), click “Legg til” (1 in below image).

You can add sub-fields to fields of the Object type via the context menu of the field (three dots to the right of the field name) or by clicking the field and select the tab Felter (Fields) in the right-side panel.

Adding a New Type

Click on the + sign in the “Typer” panel on the left side (2 in below image).

Converting Field to Type

A field can be converted to a type by clicking the three dots to the right of the field and selecting “Konverter til type” (3 in below image).

Add field and type
Add field and type and convert field to type

Editing a Type

  1. Select the type from the panel on the left side. A tree view for the type will appear in the center.
  2. Properties for the type can be edited in the right-side panel.
  3. Add new fields by clicking the Legg til (add) button at the top.
  4. Select individual fields to edit their properties in the right-side panel.
  5. Exit the type editing mode by clicking the x at the top of the model panel (next to Du redigerer nå på <type>).

Deleting a Type

  1. Select the desired type from the panel on the left side.
  2. Click the context menu (three dots) on the top field (root node) of the type and select “Delete”.

Note that it is not possible to delete types that are in use.

Type References

A type reference is a field that follows the structure of a custom type. For instance, if you have the type ‘Address’ with fields ‘StreetName’, ‘PostalCode’, and ‘Location’, adding a reference to that type will automatically add these fields. The type is displayed next to the field name in the tree view.

Type reference
Type references

Adding a Type Reference

  1. Click Legg til (add) at the top of the tree view and choose Legg til referanse (add reference).
    Add top-level reference
    Add top-level reference
  2. In the right-hand panel, select the type you wish to reference from the drop-down list “Refererer til” (refers to).
    Select type
    Select type

You can also add a type reference as a sub field: Click the three dots next to a field and select Legg til referanse.

NOTE
To add a reference as a sub field, the parent field must be of type Object.

Add reference as sub field
Add reference as sub field

Deleting a Field

Click on the three dots to the right of the node/field and select Slett (delete) from the menu.

Editing Properties of a Field

  1. Click on the node/field you want to edit to display the properties in the right-side panel.
  2. Edit the properties of the node/field as desired. The available properties for the field will vary based on the base type of the field.

Editing/Adding XSD attributes, namespaces, etc., including dataFormatId and dataFormatVersion.

This is currently not directly supported in the tool and must be done manually. Descriptions on how to do this can be found in the links below:

Generating Model Files (XSD and C#)

Once the model is ready, you can generate model files by clicking on the Generate Models button above the right panel. For the <org>-datamodels repository, a XSD file will be generated. For the app repository, both a XSD and C# model files will be generated. Remember to click Last opp dine endringer (Upload your changes) on the right side of the main menu in Altinn Studio to save your changes.

Downloading XSD

A generated XSD file can be downloaded by accessing the repository: click on the person icon in the top right corner of the page and select “Open repository.” Navigate to the desired file in App/models/ and click on the download icon.

Download XSD repo
Download XSD from repo