Defining Types and Schemas

Overview#

The ontology is the type blueprint of your model. It says what kinds of things exist, what values they carry, how they connect, what shape those values have, and what calculations run on them. Nothing else in Atlas works until the ontology exists: instances are built from types, and queries are written against them.

This article explains how to author each kind of type from the Types screen, what every field in each drawer does, and how Atlas tells you when something is wrong. Read Timebase Atlas Key Concepts first if the words domain, branch, library, instance map or compile are new to you. This article does not re-define them.

Where you author types#

Open a domain or library from the Domains or Libraries page, then select Types from the launcher on the Overview screen. The screen's own description reads:

Every Type defined in this Version, grouped by category. Select a Type to inspect it, or use Create to add one.

The tree on the left groups everything into six categories:

Above the tree sit a label filter and a Create button with a dropdown. The dropdown is the single entry point for authoring, and it lists those six kinds by name: Property Type, Data Type, Enumeration Type, Entity Type, Relationship Type, Function. Selecting one opens a drawer on the right.

Editing and deleting happen from the inspector on the right, not from the tree rows. Select a type in the tree, then Edit in the inspector reopens its drawer, and Delete sits at the foot of that drawer. A type that comes from an imported library carries the library's name on its row and has no Edit button here; open the library from the Libraries page to change it.

Note: A library uses the same six drawers and the same Types screen as a domain. A library holds only types, so it has just Overview, Types and Canvas in its launcher - no instances, no compile.

Tip: Canvas is a second view of the same content: a visual map of the entity types in this version and the relationships between them. Many people find it easier to sketch a hierarchy there and use Types for the detail.

Naming your types#

Nothing in Atlas enforces a naming style, so consistency is on you. The summary below is enough for most work; Naming Conventions for Atlas Models is the canonical reference and covers the collision rule, case sensitivity and relationship naming in full.

The house style, and the style every shipped library follows, is:

• Entity types, property types and data types: PascalCase. Motor, PumpStation, MotorTemperature, TVQ.
• Relationship types: camelCase. Every relationship type in the shipped atlas-common library is camelCase: contains, connectsTo, relatesTo, sameAs. Follow it, or your model will read inconsistently against the libraries you import.
• Domains and libraries: lower case with hyphens. Atlas does this for you: it lower-cases what you type and turns spaces into hyphens, so "Lonestar Plant" is stored as lonestar-plant.

Every drawer puts Label first and fills Name from it until you edit the name yourself. The name is the local segment of the type's internal identifier, and its help text is: "Built from the Label until you change it. Letters, digits, underscores and hyphens only."

One name space for all five kinds#

All five kinds share a single name space per domain or library, so a name can only be used once across every kind. You cannot have a property type called Tank in a domain that already has an entity type called Tank. The Name field checks this as you type and blocks the save:

Cannot create Property 'Tank': the key 'urn:atlas:ontology:brewery:Tank' is already used by a Type. All element kinds (Types, Properties, Relationships, Data Types, Functions) share one URN namespace per domain.

Define an entity type#

An entity type is a kind of thing: equipment, a process, a material, a site, a batch. It is the thing instances are made from.

1. Open the domain or library and select Types.

2. Select Create, then Entity Type. The New Entity Type drawer opens.

3. Fill in the General tab.

4. Select Create. The same drawer reads Save when you reopen a type to edit it.

   

Entity type fields#

There is a second tab, Properties, covered under Attach a property to an entity type. A third tab, Pins, resolves the open leaves of a property that is still Defer, as described under Defer properties.

Note: the parent field is called Base type. The picker lists entity types, so the framework root NodeBase is not among them. NodeBase appears in the relationship endpoint pickers instead, where it means "any entity".

Inheritance#

An entity type can specialise another entity type, and it inherits that parent's attached properties. A workable hierarchy looks like this:

• Equipment - a root entity, carrying Description and Location
• RotatingEquipment - base type Equipment, adds RPM and BearingTemperature
• Pump - base type RotatingEquipment, adds FlowRate and SuctionPressure
• Fan - base type RotatingEquipment, adds AirVolumeFlow

The compiled model keeps the whole subclass chain, so a query that asks for RotatingEquipment reaches Pump and Fan instances beneath it. A label match on the base type includes all descendants.

The quickest way to add a subtype is Derive in the inspector of the parent: it opens the New Entity Type drawer with Base type already set to the type you were looking at.

Ask Gage

Ask the designer agent: "Design a hierarchy: Equipment as the root with Description and Location properties. RotatingEquipment under Equipment adding RPM and BearingTemperature. Pump under RotatingEquipment adding FlowRate and SuctionPressure. Should any of these properties move to a different level?"

Review the plan before handing it to builder to create the types.

Define a property type#

A property type is a standalone definition of a value: Speed, MotorTemperature, Running, OEE. It is authored on its own and then attached to the types that should carry it.

1. Select Create, then Property Type. The New Property Type drawer opens.

2. Fill in the fields. This drawer has no tabs.

   

3. Select Create.

Property type fields#

The New Property Type drawer has these fields:

The drawer ends with Default sourcing strategy (None, Static, Bound or Calculated), a class-level default that every instance inherits unless an instance map overrides it. See Set a default on the property type.

Attach a property to an entity type#

Attachment lives on the entity type, not on the property. One property can be attached to any number of entity types.

1. In the Types tree, select the entity type that should carry the property.
2. Open its editor and select the Properties tab.
3. Select Link Property, then pick the property on the row that appears. Properties inherited from the base type are listed above the grid and cannot be removed here.
4. Select Save.

Because attachment is inherited, attaching a property to a parent shares it down the whole subtree. Attach Description once to Equipment and every Tank, Pump and Valve beneath it has one.

Ask Gage

Ask the builder agent: "Create a Description property (xsd:string, 'What this equipment is and what it does') and attach it to the Equipment entity type. If Equipment does not exist yet, create it first as a root entity type."

Requires the pulse:administrator role. Without it the write tools are filtered out before the agent runs, so it will simply say it cannot do this rather than returning a permission error.

Value types Atlas actually stores#

The Value type picker offers twelve XSD entries. Atlas only recognises eight of them. Use these:

Use xsd:double for measurements. It is the numeric type the shipped libraries use.

Two further options exist for people who need them:

• A union of scalars. Set Value type to One of and pick the members. A property can then accept more than one scalar type. The shipped atlas-common:Value property, for example, accepts xsd:double, xsd:string or xsd:boolean. A property left like this is shown as Defer in the editors, because its type is not yet fixed.
• A Data Type, sourced whole or field by field. On the Mappings tab, a property with a Data Type value can take one strategy for the whole value, or the Composed strategy, which gives each field its own. See Use Composed to source a data type's fields separately.
• A Data Type, with pinned fields. When you pick a Data Type as the value type, you can pin individual fields to a specific scalar. That is how you get a TVQ whose Value is specifically a double, which is the standard shape for a historian-bound measurement. The drawer surfaces this as a Pin fields table under the picked value type. A Data Type field that accepts a union, such as TVQ.Value, leaves the property Defer until you pin it. The shipped typed Tags (atlas-common:AnalogTag and its siblings) take the other route and pin Data.Value on the type; see Defer properties.

Where a property's value comes from#

A property type says what a value is. It never says where the value comes from. That is decided per instance map, on the Mappings tab, so the same property can be a fixed value on one map and a live tag on another.

See Property Sourcing Strategies for the full picture.

Why a property shows an owner you did not give it#

A property used as a field of a Data Type reports that Data Type as its owner, so a field-only property such as TVQ's Quality does not read as unattached. If a property lists an owner you did not attach it to, check whether a Data Type links it as a field.

Define a data type#

A data type defines a compound value: one property value made of several named fields that always travel together. It is the fifth kind of type, it is authored from the same screen as everything else, and it is the one people most often miss.

The canonical example ships in atlas-common and is called TVQ, for Timestamp-Value-Quality:

Any property whose value type is TVQ therefore carries all three values at once. Nearly every measurement in Atlas is shaped this way.

Create one#

1. Create the property types that will become the fields first, if they do not exist yet. A data type links existing property types; it does not create them.
2. Select Create, then Data Type. The New Data Type drawer opens.
3. Fill in Name (for example TVQ), Label and Description on the General tab.
4. Select the Properties tab and Link Property once per field, in the order you want them. The order you place them in is the field order, and the handle on each row reorders them.
5. Go back to General and set Time axis if the compound carries a sample time. The dropdown only offers fields whose value type is xsd:dateTime, so link a date-time field on the Properties tab first or the dropdown is empty.
6. Select Create.

Data type fields#

The time axis is a declaration, and it is load-bearing. It is what tells Atlas which field is the sample time. Time-range queries and point normalization both depend on it. A measurement compound with no declared time axis still compiles, but it is treated as one indivisible value: it cannot be split by time and it is excluded from instance history. If you define your own measurement compound and want history over it, declare the time axis.

Editing a data type replaces its whole field roster in one go. Adds, removes and reorders all land together, so reordering the Properties tab renumbers the field order.

Defer properties#

A property is Defer when its own value type is a union of scalars, or when its Data Type has a union-typed field that it has not pinned. Each such spot is an unresolved leaf. A Defer property can be attached to an entity type or a relationship type: the Entity and Relationship drawers list it and let you pick it. But a concrete type that uses a property with an unresolved leaf cannot compile. Validation reports it as rule O-B23 (an Error), and the domain still loads and every save still lands. Compile refuses until every leaf used by a type is pinned.

You can pin a leaf in two places:

• On the property, in its Pin fields table. Every type that uses the property gets that type. Use this when the concept has one shape everywhere, such as Temperature, which is always a double.
• On the type, on the Pins tab. Only that type, and its subtypes, get that type. Use this when the shape depends on the type. A Running property can be a boolean on Pump and a double on Tank, without declaring two properties.

The Pins tab is on the entity type, the type edit and the relationship type drawers. It has one row for each open leaf of each Defer property the type uses, including properties it inherits from a base type. Each row is a select over the members the leaf allows, for example boolean, double and string for Value. A leaf that the base type already pinned shows read-only, with the base type named.

Three rules keep a pin unambiguous:

• A property pin is final. If the property already fixed a leaf, a type cannot pin it again, and the Pins tab does not show a row for it.
• A subtype only pins a leaf its base types left open. A leaf that Equipment pinned to a double stays a double on every type beneath it.
• The pinned type must be one of the leaf's members. A leaf that accepts a double, a string or a boolean cannot be pinned to xsd:integer.

The save is refused with the reason if a pin breaks one of these. Rule O-B24 reports the same cases when it finds them in a file. A domain can also pin a property that comes from an imported library, on its own type, without editing the library. See Atlas libraries.

The Types inspector shows a chip on every property a type uses that is Defer on the property. When the type resolves it, the chip shows the resolved type, for example boolean. When the type leaves a leaf open, the chip reads Defer and names the open leaves.

Define an enumeration type#

An enumeration type is a fixed list of named members, each with a key: the operating states of a machine, a product code, a quality band. A property bound to an enumeration still stores the key (20), and the model knows that 20 means Running, so the Instance Inspector, queries and Bridge exports can show the name as well as the number.

1. Select Create, then Enumeration Type. The New Enumeration Type drawer opens.
2. Fill in the General tab, including Key type.
3. On the Members tab, select + Add member once per member and fill in its Key, Name and Label. The arrows on each row reorder the members.
4. Select Create.

Enumeration type fields#

Bind a property to an enumeration#

The binding lives on the property type, in its Pin fields table. Give the property a value type whose leaf is the enumeration's key type, then pick the enumeration in the Enumeration type column of that row. The shipped juice-factory-common:StateData property does exactly this: its value type is TVQ, its TVQ.Value is pinned to long, and the enumeration beside it is Filler State. A type pin on the Pins tab can bind an enumeration the same way.

The key type and the pinned type must agree. Pin TVQ.Value to double and bind an enumeration keyed by Long, and validation reports rule O-B16; name something that is not an enumeration and it reports O-B15. A malformed enumeration in a hand-edited file reports O-B17. All three are in the Validation Rules Reference.

Define a relationship type#

A relationship type defines a named, directed connection between two entity types. Relationships are what let a query walk from a site, to its lines, to its equipment in one hop chain.

1. Select Create, then Relationship Type. The New Relationship Type drawer opens.

2. Fill in the General tab.

3. Use the Properties tab if the connection itself carries data.

   

4. Select Create.

Relationship type fields#

Abstract types#

Switch on Abstract on an Entity Type or a Relationship Type and it becomes derivation-only: it can still be the Base type for other types, but nothing can be an instance of it.

This is how you say "every pump has these properties, but nothing is just a pump". Attach the shared properties to an abstract Pump, derive CentrifugalPump and PositiveDisplacementPump from it, and the model refuses the vague case rather than relying on everyone remembering not to author it.

What changes once a type is abstract:

That last row is the one worth planning around. Marking a type abstract does not break a model that already has instances of it, and it does not block a compile. It raises a warning against each one so you can re-type them at your own pace. See Validation Rules Reference.

Unticking Abstract restores instantiation immediately. The marker is a flag on the type, not a structural change, so there is nothing to migrate in either direction.

Containment or association#

Every relationship type picks a root, and the choice matters:

• Contains is physical or logical containment. It is what drives the hierarchy views: a contains edge is why an area appears nested under a site on the Instances screen.
• Relationship is everything else: a flow between two machines, a logical association, an identity assertion.

The shipped atlas-common library gives you contains (rooted at Contains) and connectsTo, relatesTo and sameAs (rooted at Relationship), all with both endpoints open to anything. Import the library and reuse them rather than defining near-duplicates.

Data on the connection itself#

A relationship type can carry its own properties, added on the drawer's Properties tab. A feeds relationship can carry a flow rate; a contains relationship can carry a commissioning date.

A relationship in Atlas is a first-class thing, not a line on a diagram. It gets its own identity, its own property values, and its own instance map with a top-level source and target.

Relationship types inherit, and narrowing is enforced#

A relationship type can specialise another relationship type by naming it as the Base type. When it does, its endpoints may only narrow: a child's Source and Target must be subtypes of the parent's. Break that and validation rule O-B10 fires:

Relationship 'urn:atlas:ontology:brewery:pumpFeedsTank' narrows its Source from 'Equipment' to 'Batch', which is not a subtype of the parent's Source.

There is no cardinality setting#

Relationship participation is unconstrained: any number of edges of a given type may exist between any pair of instances whose types satisfy the Source and Target. There is no one-to-one or one-to-many setting in the drawer, the API or the stored file.

If a rule like "a machine has exactly one control panel" matters to you, it is a modelling convention you enforce in how you build your instance maps, not something Atlas checks.

Ask Gage

Ask the designer agent: "Design two relationships for Equipment: one called 'contains' rooted at Contains for physical containment, one called 'requires' rooted at Relationship meaning an Equipment requires a Tool to operate. What should their descriptions be? Should either have type constraints?"

Review the plan. When ready, hand it to builder to create the relationships.

Functions#

A function is reusable calculation logic: named parameters, one output, defined once and referenced from any property that should be calculated. Functions are the fifth category on the Types screen and are created from the same Create dropdown.

Functions are covered in Calculations and Functions.

Import types from a library#

If the types you need already exist in a library, import the library into your domain rather than redefining them. Once imported, every type in the library is available as a base type, as a property to attach, and as a relationship endpoint.

You can also author into a library. A library gets the same Types screen and the same five drawers as a domain, so building a shared vocabulary for several plants is the same job you have just read about, done in a library instead of a domain.

Libraries and imports are covered in Atlas Libraries.

Use the AI assistant to draft your types#

Describing your plant to the assistant is the fastest way to a first draft.

1. Open the AI assistant panel.
2. Describe your domain: what equipment exists, what it measures, what units it uses, and how it is organised.
3. The assistant creates entity types, property types, relationship types, data types and functions, and proposes a hierarchy where your description has a natural one.
4. Review what it produced on the Types screen. Accept it, ask for changes in plain words ("attach FlowRate to Pump as well", "add a description to the contains relationship type"), or edit individual types in the drawers.
5. Check the Outstanding items panel on the Overview screen before you compile.

The assistant writes types in batches, so one instruction becomes one saved change rather than a dozen. Ask it to list what already exists before you ask it to add something, otherwise it may propose a type you already have under a slightly different name.

Check your work#

Atlas validates continuously as you save. You do not have to compile to find out what is wrong.

The Outstanding items panel#

The domain or library Overview screen (and the Domain Lifecycle screen) shows a panel headed Outstanding items with a "{n} to fix" chip, whenever anything is outstanding. Its body copy reads, verbatim:

Your changes are saved. These items don't block saving - fix them in any order - but this Domain Version can't be compiled until they're resolved.

Inside, items are split into two lists:

• To fix - errors. These block the compile.
• Advisory - warnings. These never block anything.

If one of the items stops the file being read at all, a red line appears above the lists:

One of these items stops the file being read, so the list below may be incomplete. Resolve it first.

Fix that one first, save, and the rest of the list becomes trustworthy.

Rule IDs#

Every item carries a rule ID, shown next to its severity. The letters tell you where to look:

O-A1 and O-A2 are the fatal ones that truncate the rest of the list. Everything you author on the Types screen produces O-… rules.

The full catalogue, with what triggers each rule and how to clear it, is in the Validation Rules Reference.

Saved, and waiting to be published#

A clean save commits straight through to the branch and there is nothing to publish. A save that leaves error-severity items outstanding is held in a private draft session of your own, so the branch does not move until you publish it.

While you hold a draft, a second panel appears on Overview, headed Unpublished changes, with a chip reading either Ready to publish or "{n} to fix first". Clear the outstanding items, then select Publish to {branch}. To set the work aside instead, use Discard changes.

Delete a type#

Select the type in the tree, select Edit in the inspector, then Delete at the foot of the drawer. Deletion is permanent and is not undoable, and several kinds are blocked while something still depends on them. The confirmation dialogs say so:

When a delete is blocked, Atlas returns the list of things depending on the type. Clear those first, then delete.

Troubleshooting#

Related articles#