Independent IFS Cloud practice · Data contracts
An IFS Cloud data contract turns a master data record into a product consumers can rely on
An IFS Cloud data contract is a machine-readable file, kept under version control, that describes one master data product: which interface serves it, its schema and keys, what its fields mean, which quality rules it meets, who may read it and how changes are announced. It turns the agreement between the domain that owns the data and the domains that consume it into something a pipeline can test.
This article covers what goes into the contract, where each part comes from in IFS Cloud, and how the contract is versioned and published. Choosing the master data is covered in enabling data mesh in IFS Cloud, and assigning owners in data domain mapping.
Key takeaways
- A data contract has seven parts: owner, interface, schema and keys, definitions, quality rules, access and versioning.
- The schema comes from IFS Cloud itself: the API Explorer documents each projection with OpenAPI v2 and OpenAPI v3 specifications. Store the specification in Git next to the contract.
- Adding a field is a minor version, removing or renaming a field is a major version, and a change to allowed values is decided case by case.
- Row-level access through custom data access control is enforced for APIs only, so a consumer reading the database directly is not filtered by it. Name the channel in the contract.
- Re-check every contract against the projection specification after each IFS Cloud release update.
1.What is a data contract for IFS Cloud master data?
A data contract for IFS Cloud master data is a formal description of a data product that both the producing and the consuming domains accept, written so that software can check it. A sharing agreement says in words what the procurement domain promises to deliver to finance. The contract says the same in a file: these fields, with these types and keys, refreshed this often, meeting these tests.
The difference matters when something changes. A sharing agreement is read when there is a dispute. A contract is read by a pipeline on every run, so a broken promise shows up as a failed test before a consumer sees wrong figures. How the agreement itself is negotiated is in confirm sharing agreements.
2.What goes into the contract, and where does each part come from?
Each part of the contract has a source, either in IFS Cloud or in the domain’s own decisions.
| Part | Content | Source |
|---|---|---|
| Owner | Domain, owner, steward, contact for incidents | The data domain map |
| Interface | The projection that serves the product, or the analytics data set built from it | API Explorer; the Debug Console on a page shows which projection it uses |
| Schema and keys | Fields, types, which fields are mandatory, the key of a record | The OpenAPI v3 specification of the projection |
| Definitions | Business meaning of each field and each allowed value | The domain’s definitions, agreed with consumers |
| Quality rules | Tests with a threshold: completeness, uniqueness, consistency, freshness | The domain’s quality rules |
| Access | Which permission set grants read access, and any row-level restriction | Permission sets and custom data access control in IFS Cloud |
| Versioning and change notice | Current version, change policy, notice period, review after each release update | The domain’s change policy |
The schema and keys part needs care with site. An inventory part in IFS Cloud belongs to a site: the 24R2 analysis model documentation states that “each contract (site) has its own set of inventory parts” (IFS Cloud 24R2). A contract that declares the part number alone as the key will reject valid data the first time the same part exists at two sites.
3.Where does the schema come from in IFS Cloud?
The schema of a master data contract comes from the projection that serves the data, because IFS Cloud already documents every projection in a standard format. The IFS Cloud 25R1 API Explorer documentation states that the projections used by IFS Cloud Web “can also be reused for integration purposes”, and directs readers to the API Explorer for details “including OpenAPI v2, OpenAPI v3”. To find the projection behind a page, it suggests enabling the Debug Console, which shows page information including projection names.
In practice the steps are:
- Find the projection. Open the page where the master data is maintained, enable the Debug Console and note the projection name.
- Take the specification. Open that projection in the API Explorer and save its OpenAPI v3 specification.
- Cut it down. Keep only the entity sets and fields the product actually promises. A contract that promises everything in the projection cannot change anything without a major version.
- Commit it. Put the specification and the contract in the same Git repository, reviewed by the domain owner like any other change.
For analytics consumers the interface can be a data set in the lake instead of the projection. The IFS Cloud 24R2 Data Services documentation states that “The Data Pump will do the actual data movement and Parquet file generation” and that the main data store is a Data Lake (ADLS Gen 2). The contract then names the data set, its refresh schedule and the projection or source it was built from.
4.How are quality rules and access written into the contract?
Quality rules go into the contract as tests with a threshold, so a pipeline can run them and report pass or fail. IFS Cloud validates each record when it is saved, for example by rejecting an empty mandatory field, but that validation looks at one record at a time. Rules that span records or compare field groups are the ones the contract adds. For a supplier product, typical examples are:
- every active supplier has a tax code in the invoice defaults;
- payment terms in the purchase defaults match payment terms in the invoice defaults;
- no two active suppliers share the same company registration number;
- the data set in the lake is no older than the agreed refresh interval.
The rules can be expressed in a JSON Schema or YAML file next to the contract and executed with a test framework such as dbt in the CI pipeline. The tool matters less than the rule that a failed test blocks publication of a new version.
Access is written as names of IFS Cloud objects. Read access to projections is granted through permission sets, which can grant permissions to “Projections, Lobby Pages, Workflows, Database Tasks and Database Task Chains” (IFS Cloud 25R1, creating permission sets). Row-level restrictions use custom data access control, which the 25R1 documentation describes as a feature that “restricts access to specific Data in APIs”. The same page states that “Access Control Lists (ACLs) are enforced solely for APIs”, so a user who reads data another way, such as through a direct database connection, can see different data (IFS Cloud 25R1, custom data access control considerations). A contract that relies on row-level restrictions must therefore state that consumers read through the API.
5.How is a data contract versioned?
A data contract is versioned by the effect of a change on consumers: a change that cannot break a consumer is a minor version, and a change that can is a major version.
| Change | Effect on consumers | Version |
|---|---|---|
| Add a field | Non-breaking: existing consumers ignore it | Minor |
| Remove or rename a field | Breaking: consumers that read it fail | Major, with a notice period |
| Change the allowed values of a field | Depends: a new value can break a consumer that maps every value | Patch or minor, decided with the consumers |
| Tighten a quality threshold | Non-breaking for consumers, a new obligation for the producer | Minor |
IFS Cloud release updates are the other source of change. After each update, compare the new OpenAPI specification of every projection named in a contract with the version in Git, before consumers find the difference. The difference between service updates and release updates is explained in IFS Cloud service update vs release update, and the wider preparation in IFS Cloud upgrade readiness.
6.How is a contract published, and what is the checklist for the first one?
A contract is published through the same review path as code: export, version, validate, register and distribute.
- Export. Save the OpenAPI v3 specification of the projection from the API Explorer.
- Version. Commit the specification and contract to Git and tag the version, for example v1.2.0.
- Validate. Let the CI pipeline lint the contract and run its quality tests.
- Register. Add the approved contract to the catalog your consumers search. The IFS Data Catalog scans IFS data sources and creates metadata catalog entries; the contract adds the owner, definitions and promises that a scan cannot know.
- Distribute. Grant the permission set to the consuming domain and, for analytics, schedule the data set in the lake.
Ten checks for the first contract:
- The master data product has a named owner and steward in the domain map.
- The projection is identified and its OpenAPI v3 specification is in Git.
- The specification is cut down to the fields the product promises.
- The key includes site wherever the record belongs to a site.
- Every promised field has a written business definition.
- Quality rules are written as tests with thresholds.
- Tests run in CI and a failure blocks a new version.
- Read access is a named permission set, and any row-level restriction is documented with the channel it applies to.
- The versioning policy and notice period are written and accepted by consumers.
- A review is planned after the next IFS Cloud release update.
7.Frequently asked questions
What is an IFS Cloud data contract?
An IFS Cloud data contract is a version-controlled file that describes one data product built on IFS Cloud data: its owner, the projection or data set that serves it, its schema and keys, the business definitions of its fields, its quality rules, its access rules and its versioning policy. Pipelines test the data against it on every run.
Is an IFS Cloud projection already a data contract?
An IFS Cloud projection is not a data contract by itself. The projection and its OpenAPI specification describe the technical interface. The data contract adds what IFS Cloud does not know: the owner, the business meaning of fields, quality thresholds, the subset of fields that is promised, and how changes are announced to consumers.
How do data contracts reduce the cost of broken integrations with IFS Cloud?
Data contracts reduce the cost of broken integrations with IFS Cloud by moving the failure earlier. A removed or renamed field, a changed allowed value or a quality breach fails a test in the CI pipeline before a new version is published, instead of being found by a consumer in a wrong report or a failed interface run.
Can data contracts be used during a migration to IFS Cloud?
Data contracts can be used during a migration to IFS Cloud as stable target interfaces. Analytics teams build reports against the contract for the future IFS Cloud structure while the migration is still running, and the migrated data has to pass the contract’s quality tests before the product is released to consumers.
Does custom data access control in IFS Cloud protect data read from the database?
Custom data access control in IFS Cloud filters data served through APIs. The IFS Cloud 25R1 documentation states that its access control lists are enforced solely for APIs, so data read through a direct database connection is not filtered by them. A data contract that depends on row-level restrictions must require consumers to read through the API.
8.About the author
Dariusz Myśliwiec: 18 years hands-on with IFS (Apps 7.5–10 and IFS Cloud). Based in Kraków, delivering remotely across Europe and globally through an independent practice. You talk to the consultant who does the work, not a sales layer.
If you want help writing the first data contract for your IFS Cloud master data, from the projection to the permission set, see my services for IFS Cloud.
IFS is a registered trademark of IFS AB; this practice is not affiliated with IFS AB.
Pilot one contract on one master data record
Pick the supplier or the part, find its projection, cut the specification down to what a consumer needs and write three quality tests. That is enough to see whether your domain owners are ready to stand behind a contract.
Book a call about your first data contract Read: what is data mesh
