OpenFactory Unified Namespace Schemas#

OpenFactory Unified Namespace (UNS) Schema

This module defines the structure, constraints, validation logic, and helpers for managing the Unified Namespace (UNS) within OpenFactory.

The UNS provides a hierarchical naming scheme used to organize assets and their attributes across the OpenFactory platform. The structure and rules are defined via a YAML schema file that is loaded and validated here.

Components:#

  • ConstraintType: Type alias for field constraints (e.g., “ANY”, enum, or literal).

  • NamespaceItem: Pydantic model representing one level in the namespace structure.

  • UNSSchemaModel: Validates schema structure loaded from YAML.

  • UNSSchema: Main interface for schema loading, validation, and UNS path generation.

  • AttachUNSMixin: Mixin for enriching objects with validated UNS information.

Key Features:#

  • Validates schema structure via Pydantic

  • Enforces ordering and constraints of namespace levels

  • Supports constant values, enumerations, and wildcards

  • Automatically generates UNS paths for assets

  • Mix-in support for attaching UNS info to models with uuid/uns

Typical Usage:#

  1. Load and validate schema:

    >>> schema = UNSSchema("path/to/uns_schema.yaml")

  2. Extract and validate UNS fields for an asset:

    >>> fields = schema.extract_uns_fields("uuid-123", asset_dict)

  3. Generate a standardized UNS path:

    >>> path = schema.generate_uns_path(fields)

  4. Use AttachUNSMixin in your asset model to auto-enrich with UNS:

    >>> class Asset(AttachUNSMixin):
>>>     uuid: str
>>>     uns: Optional[Dict[str, Any]]
class openfactory.schemas.uns.AttachUNSMixin[source]#

Bases: object

Mixin that provides UNS validation and enrichment capabilities.

Requires the implementing class to have:

  • uuid: str

  • uns: Optional[Dict[str, Any]] = None

attach_uns(uns_schema)[source]#

Validate and enrich the object’s uns block using the provided UNSSchema.

On success, replaces self.uns with:

{
    "levels": { ... fields as returned by extract_uns_fields ... },
    "uns_id": "<generated path>"
}
Return type:

None

Parameters:

uns_schema (UNSSchema) – The UNS schema instance used for validation and path generation.

Raises:

ValueError – If validation fails.

openfactory.schemas.uns.ConstraintType = str | list[str]#

Represents allowed values for UNS schema fields. Can be a string, or a list of allowed strings for the UNS field. The special string “ANY” is interpreted as any value is allowed.

class openfactory.schemas.uns.NamespaceItem(root=PydanticUndefined, **data)[source]#

Bases: RootModel[Dict[str, Union[str, list[str]]]]

Represents a single item in the OpenFactory namespace_structure.

Each item is expected to be a dictionary with exactly one key, where the key is the level name (e.g., ‘inc’, ‘area’) and the value is the constraint for that level (e.g., a string, list of strings, or ‘ANY’).

check_one_key()[source]#

Validates that the item has exactly one key.

Return type:

NamespaceItem

Returns:

NamespaceItem – The validated instance.

Raises:

ValueError – If the dictionary does not contain exactly one key.

key()[source]#

Returns the single key of the namespace item.

Return type:

str

Returns:

str – The level name (e.g., ‘inc’, ‘station’).

model_config = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

value()[source]#

Returns the constraint value associated with the key.

Return type:

str | list[str]

Returns:

ConstraintType – The constraint (e.g., string, list of strings, or ‘ANY’).

class openfactory.schemas.uns.UNSSchema(schema_yaml_file=None)[source]#

Bases: object

Represents and validates the Unified Namespace (UNS) schema.

This class loads a schema definition from a YAML file, validates it using the UNSSchemaModel Pydantic model, and provides methods to extract, validate, and generate UNS paths for OpenFactory assets.

separator#

The character used to separate fields in the UNS template.

Type:

str

template_fields#

Fields extracted from the UNS template, including ‘attribute’.

Type:

List[str]

allowed_values#

Mapping of UNS level names to their allowed values and constraints.

Type:

Dict[str, openfactory.schemas.uns.ConstraintType]

Note

The validation is performed by the UNSSchemaModel. Any schema format or constraint errors will be reported as part of the standard Pydantic validation error output.

__init__(schema_yaml_file=None)[source]#

Initializes the UNS schema from a YAML file by loading and validating it.

Parameters:

schema_yaml_file (str) – Path to the UNS schema YAML file.

Raises:

ValueError – If the schema content does not conform to the expected UNS schema model.

extract_uns_fields(asset_uuid, uns_dict)[source]#

Extracts all UNS hierarchy fields for an asset, based on the template and schema.

This includes:

  • Constant fields (e.g., “inc”: “OpenFactory”) defined in the schema. If the asset defines them with a different value, an error is raised.

  • Constrained fields (e.g., from an enum list or “ANY”) that are expected from the asset dictionary.

  • Excludes the final “attribute” field from the UNS path.

  • If the “asset” field is not provided explicitly, it is populated from the “uuid” field of the asset.

Parameters:

uns_dict (Dict[str, Any]) – The dictionary representing a single asset configuration.

Returns:

Dict[str, Any] –

A dictionary mapping each field (excluding “attribute”) to its resolved value,

combining schema-defined constants and asset-provided values.

Raises:

ValueError – If a constant field is overridden incorrectly, if a constraint is malformed, or if “asset” is missing and “uuid” is not defined.

Return type:

Dict[str, Any]

generate_uns_path(fields)[source]#

Generates the UNS path string by joining the hierarchy fields with the template separator.

Return type:

str

Parameters:

fields (Dict[str, Any]) – The validated UNS hierarchy fields.

Returns:

str – The generated UNS path string without the ‘attribute’ field.

validate_uns_fields(asset_name, fields)[source]#

Validates UNS fields in the asset configuration.

Validates that: - Asset fields form a contiguous prefix (no gaps) of the UNS template (excluding constant fields and ‘attribute’) - The last asset-provided field is ‘asset’ - Field values match allowed constraints

Constant fields are validated during extraction and are not checked here.

Parameters:

  • asset_name (str) – Asset identifier (used only for error reporting).

  • fields (Dict[str, Any]) – UNS-relevant fields extracted from asset config (with extract_uns_fields).

Raises:

ValueError – If fields are missing, incorrectly ordered, or values are invalid.

class openfactory.schemas.uns.UNSSchemaModel(**data)[source]#

Bases: BaseModel

Represents the schema definition for the OpenFactory Unified Namespace (UNS).

namespace_structure#

A list of namespace levels with their constraints.

Type:

List[NamespaceItem]

uns_template#

A string template defining the path structure using level names separated by a character (e.g., ‘inc.area.station.asset.attribute’).

Type:

str

check_template_fields()[source]#

Validates uns_template.

Validates that the uns_template:

  • Contains a recognizable separator character.

  • Ends with the ‘attribute’ field.

  • References only fields defined in the namespace_structure.

Returns:

UNSSchemaModel – The validated instance.

Raises:

  • ValueError – If the separator cannot be determined.

  • ValueError – If the template does not end with ‘attribute’.

  • ValueError – If the template references fields not defined in the namespace structure.

Return type:

UNSSchemaModel

model_config = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].