UNS OpenHubDocumentation

Schema administration

How Schema works

Schema separates reusable vocabulary from live context. Start with a solution profile or Blank, then use reviewed changes, tenant customizations, and service or MQTT suggestions without changing live topics or concrete asset paths.

Applies to
Schema and Solutions & packages · profiles, customizations, and discovered context
Guide version
1.2

Worked example

Example: a temperature value

A small set of schema entries makes a published temperature easier to understand without changing the topic or value.

Object type furnace

Reusable definition of what a furnace is and which attributes belong to it.

Attribute type temperature

Definition of the value shape, label, description, and preferred unit.

Measurement unit temperature / celsius / °C

Reusable catalog entry that describes the value; it does not convert it.

Relationship rule furnace-feeds-line

Optional rule that describes which object types can be connected and what the connection means.

Source and ownership solution package, tenant customization, or reviewed service contract

Provenance determines where the definition is managed and prevents one source from silently taking ownership from another.

Procedure

Follow the task in order

  1. 1
    Read the Overview before editingOverview shows the installed solution, local customizations, service schema suggestions, provider readiness, and live MQTT context. Exact means the installed package vocabulary is unchanged; Customized identifies separate tenant changes, while Drifted needs inspection before another rollout.
  2. 2
    Use a solution profile as the baselineChoose an available starter profile when its reusable packages fit this deployment, or choose Blank to begin with the secure generic core. Installing a profile adds managed vocabulary; it does not create live Assets or require every optional capability immediately.
  3. 3
    Review a profile change before applying itIn Solutions & packages, open Solution catalog and inspect the proposed package, definition, and retained-data impact. A profile switch or migration applies only after its reviewed plan passes the current ownership, compatibility, and permission checks.
  4. 4
    Keep tenant customizations separateUse Manage local definitions for a tenant-only addition that does not belong in a reusable package. Review the proposed definition once before applying it; the installed package remains unchanged and the customization receives its own revision and provenance.
  5. 5
    Review service schema contracts explicitlyA service can publish one retained, versioned schema contract. Schema shows the proposed definitions and field-level changes before adoption; ownership or compatibility conflicts block the apply action instead of silently overwriting existing vocabulary.
  6. 6
    Treat MQTT metadata as observationCompatible publisher metadata may suggest a reusable attribute or object type. An administrator must open Review and apply that one suggestion deliberately. Assets, ObjectIds, topic paths, payload schemas, and runtime-only metadata remain evidence and are never promoted automatically.
  7. 7
    Browse before creating another definitionUse search, record type, status, and usage filters to find existing vocabulary. Manage package-owned definitions through the solution or package candidate; use the individual form guides for deliberate tenant-owned definitions.
  8. 8
    Treat Maintenance as recovery toolingUse Maintenance, profile recovery, or rollback only after reading the plan and confirmation. Recovery requires the relevant exact historical evidence; it does not replace normal profile, customization, or source-review workflows. Ask the system maintainer before resolving a blocked migration or recovery plan.

Expected result

What you should have

A governed vocabulary with a clear package baseline, separately reviewed profile changes and tenant customizations, and reviewable service or MQTT evidence. Live publishers keep publishing their own values and paths; Schema records reusable meaning and provenance.

Boundaries

Important boundaries

  • Installing or customizing vocabulary does not create an Asset, change a live topic, or rewrite its values.
  • For package-owned object types, attributes, and relationship rules, use Edit package definition from Schema. Changes stay in a package candidate until reviewed and applied.
  • A service contract must be retained and versioned, and it remains a suggestion until an administrator reviews it.
  • MQTT publisher metadata never receives automatic ownership. Conflicting publisher values or existing ownership block promotion.
  • Prefer a new key when an active definition would need a different meaning; changing an established key can confuse publishers and consumers.

FAQ

Common questions

What do Exact, Customized, and Drifted mean?

Exact means the active package vocabulary matches the installed solution profile. Customized means separate tenant definitions or overlays are active. Drifted means the effective vocabulary no longer matches the expected reviewed state and should be inspected before another rollout.

Do live MQTT topics become Schema definitions automatically?

No. MQTT remains observation only. Reusable attribute or object-type metadata can appear as a review suggestion, but an administrator must promote it explicitly; concrete assets, ObjectIds, topic paths, payload schemas, and runtime metadata stay unchanged.

Can a microservice provide its own Schema?

Yes. A service can publish one retained, versioned schema contract. The controller presents a field-level review and applies it only when ownership and compatibility checks succeed.

Must every tenant-specific definition become a package?

No. Use a local definition for tenant-only vocabulary. It remains separate from the installed solution, so a later package update cannot silently take ownership of it.

How do I change or update a solution profile?

Open Solutions & packages, use Solution catalog to select the target, and review the plan before applying it. The plan presents the package and definition impact and stops if ownership, compatibility, or access checks are not satisfied.

Can I roll a profile back?

Only through the reviewed rollback flow. The current profile must be exact and the target needs verified historical profile evidence with its original package versions. If the plan is blocked, keep the catalog unchanged and ask the system maintainer to resolve the prerequisite.

This versioned public guide is maintained with the UNS OpenHub website and linked directly from the controller where the task applies.