OpenFactory Unified Namespace Schemas#

OpenFactory Unified Namespace (UNS) Schema.

openfactory.schemas.uns.ConstraintType#

Represents allowed constraints for UNS schema fields. Can be “ANY”, a specific string, or a list of allowed strings.

alias of Literal[‘ANY’] | str | List[str]

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

Bases: RootModel[Dict[str, Union[Literal['ANY'], 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: ClassVar[ConfigDict] = {}#

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:

Union[Literal['ANY'], str, List[str]]

Returns:

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

class openfactory.schemas.uns.UNSSchema(schema_yaml_file='${OPENFACTORY_UNS_SCHEMA}')[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='${OPENFACTORY_UNS_SCHEMA}')[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_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:

asset_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: ClassVar[ConfigDict] = {}#

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