SMIA ecosystem: SMIA-I KB¶

SMIA-I KB (Knowledge Base) provides system information to identify SMIA agents and their CSS functional information for dynamic scenarios. This Knowledge Base offers identifying manufacturing capabilities and associated SMIA instances. The suffix “-I” denotes its function as a support infrastructure component for SMIA instances but not an agent itself, offering complete decoupling.

Note

SMIA-I KB has been used in the Flexible small-scale manufacturing, which has an associated visual resource available on Youtube.

Source Code Reference¶

The SMIA-I KB leverages an OWL ontological database, enabling efficient management of CSS-related information. Developed in Python, it leverages OWLready2, the same ontology library as SMIA. To ensure consistency in its connectivity with the external infrastructure, a homogeneous interaction pattern based on the OpenAPI specification is used.

Deployment Environment¶

SMIA-I KB can be deployed locally by downloading the source code and simply running the module in the src directory with python -m swagger_server. However, it is recommended to deploy it in a virtualized environment for a self-contained deployment environment. The Docker image of the SMIA-I KB is available in the SMIA Docker Hub.

A valid virtualized environment containing SMIA-I KB can be easily generated using the tool provided in this documentation platform: SMIA Environment Builder. To achieve the desired result, in step 2 SMIA-I KB must be selected within the infrastructure components.

The deployment command depends on the selected virtualization environment: Docker Compose (docker compose up) or Kubernetes (kubectl apply -f deploy/). Once deployed, the SMIA-I KB initializes the server and exposes its REST API at the configured port.

Note

As mentioned in the SMIA Environment Builder, if SMIA-I KB is deployed for the SMIA agentic environment, the deployment of the SMIA ecosystem: SMIA ISM infrastructure component is required to mediate agent interactions with the Knowledge Base.

Interface and Interaction¶

The SMIA-I KB exposes a homogeneous and standardized HTTP/REST API following the OpenAPI 3.0.4 specification, built on top of Flask Python package. This API provides full programmatic control over the Capability-Skill-Service (CSS) model Knowledge Base, enabling SMIA agents and external manufacturing applications to query capabilities, manage skill parameters, and discover registered SMIA agent instances. All ontology resources (capabilities, skills, constraints, SMIA instances, etc.) are managed through this API, which acts as the exclusive interaction gateway for external components such as SMIA agents (mediated by SMIA ISM) and the AAS Repository.

Note

The SMIA-I KB server listens on port 8080 and exposes the API at the base path /api/v3. It is recommended to containerize it, since it is available as a Docker image under ekhurtado/smia-tools:latest-smia-kb.

API overview¶

Base URL	`https://<SMIA-I KB IP>:<SMIA-I KB PORT>/api/v3`
Content Type	`application/json` (`application/xml` also supported)
Specification	OpenAPI 3.0.4
Identifier Encoding	Ontology IRIs must be Base64-URL-encoded when used as path parameters. The Serialization API provides encode/decode utilities for this purpose.

Tip

SMIA-I KB also offers a web-based graphical interface accessible via the path /api/v3/ui/. It provides detailed information on the complete API, as well as interactive utilities that allow users to send HTTP requests to each specific API and receive the response, along with examples to ensure that these requests comply with the specification.

API reference¶

The API is organized into several functional areas corresponding to the CSS (Capability-Skill-Service) model and SMIA operative environment. The Figure: SMIA-I KB interface illustrates the main resource groups. The following list provides details on each of them.

Note

The Serialization API is not shown in the figure because it does not interact with the internal database. It provides useful endpoints for users working with AAS and OWL identifiers (capabilityIdentifier, skillIdentifier), since the OpenAPI specification requires Base64-URL-encoded parameters. The Serialization API provides encode/decode utilities for this purpose.

Capability API

This API manages the Capability layer of the CSS model, providing endpoints for creating, reading, updating, and deleting Capabilities and their related elements (constraints, skill references, assets).

Path	Method	Description	Parameters
`/capabilities`	GET	Returns all capabilities
	POST	Add a new capability	Body: `Capability` (REF)

`/capabilities/$identifiers`	GET	Returns all capability IRI identifiers

`/capabilities/{capabilityIdentifier}`	GET	Returns a specific capability	Path: `capabilityIdentifier` (Base64)
	PUT	Updates an existing capability	Path: `capabilityIdentifier` (Base64); Body: `Capability` (REF)
	DELETE	Deletes a specific capability	Path: `capabilityIdentifier` (Base64)

`/capabilities/{capabilityIdentifier}/skill-refs`	GET	Returns skill references of a capability	Path: `capabilityIdentifier` (Base64)
	POST	Add a skill reference to a capability	Path: `capabilityIdentifier` (Base64); Body: `ReferenceIRI` (REF)

`/capabilities/{capabilityIdentifier}/capabilitiesConstraints`	GET	Returns constraints of a capability	Path: `capabilityIdentifier` (Base64)
	POST	Add a constraint to a capability	Path: `capabilityIdentifier` (Base64); Body: `CapabilityConstraint` (REF)

`/capabilities/{capabilityIdentifier}/capabilitiesConstraints/{capabilityConstraintIdentifier}`	GET	Returns a specific constraint	Path: both identifiers (Base64)
	PUT	Updates a constraint	Path: both identifiers; Body: `CapabilityConstraint` (REF)
	DELETE	Deletes a constraint	Path: both identifiers

`/capabilities/{capabilityIdentifier}/assets`	GET	Returns assets of a capability	Path: `capabilityIdentifier` (Base64)
	POST	Add an asset to a capability	Path: `capabilityIdentifier` (Base64); Body: plain string (asset ID)

Skill API

This API manages the Skill layer of the CSS model, providing endpoints for creating, reading, updating, and deleting Skills and their associated parameters.

Path	Method	Description	Parameters
`/skills`	GET	Returns all skills
	POST	Add a new skill	Body: `Skill` (REF)

`/skills/$identifiers`	GET	Returns all skill IRI identifiers

`/skills/{skillIdentifier}`	GET	Returns a specific skill by IRI	Path: `skillIdentifier` (Base64)
	PUT	Updates an existing skill	Path: `skillIdentifier` (Base64); Body: `Skill` (REF)
	DELETE	Deletes a skill	Path: `skillIdentifier` (Base64)

`/skills/{skillIdentifier}/parameters`	GET	Returns parameters of a skill	Path: `skillIdentifier` (Base64)
	POST	Add a parameter to a skill	Path: `skillIdentifier` (Base64); Body: `SkillParameter` (REF)

`/skills/{skillIdentifier}/parameters/{skillParameterIdentifier}`	GET	Returns a specific parameter	Path: both identifiers (Base64)
	PUT	Updates a skill parameter	Path: both identifiers; Body: `Skill` (REF)
	DELETE	Deletes a skill parameter	Path: both identifiers

SMIA API

This API manages deployed SMIA agent instances, providing endpoints for registering and querying SMIA instances that are part of the normalized manufacturing ecosystem.

Path	Method	Description	Parameters
`/smiaInstances`	GET	Returns all registered SMIA instances
	POST	Register a new SMIA instance	Body: `SMIAinstance` (REF)

`/smiaInstances/$identifiers`	GET	Returns all SMIA instance identifiers

`/smiaInstances/{smiaInstanceIdentifier}`	GET	Returns a specific SMIA instance	Path: `smiaInstanceIdentifier`
	PUT	Updates an existing SMIA instance	Path: `smiaInstanceIdentifier`; Body: `SMIAinstance` (REF)
	DELETE	Deletes a SMIA instance	Path: `smiaInstanceIdentifier`

AAS Repository API

This API manages the interaction with an AAS server, providing endpoints for integrating with an AAS Repository to automatically extract CSS information into the Knowledge Base.

Path	Method	Description	Parameters
`/checkAASRepository`	GET	Checks availability of the AAS Repository	Query: `AASRepositoryURL`

`/extractCSSFromAASRepository`	GET	Extracts CSS information from the AAS Repository	Query: `AASRepositoryURL`

Serialization API

Utility endpoints for encoding and decoding ontology IRIs in Base64-URL format. These are essential for constructing path parameters in the Capability and Skill API endpoints, which require encoded identifiers.

Path	Method	Description	Parameters
`/serialization`	PUT	Encodes a plain string into Base64-URL format	Body: `ReferenceIRI` (REF) (plain string)

`/deserialization`	PUT	Decodes a Base64-URL string back to plain text	Body: `ReferenceIRIencoded` (REF)

API schemas¶

The following schemas define the data structures that are used in request bodies and responses across the API. Although the format is defined in an abstract manner and supports both JSON and XML serialization, it is recommended to use JSON.

Capability schema

Capability¶
Field	Type	Req.	Description
`iri`	`ReferenceIRI`	Yes	Unique ontology IRI identifier (e.g., `http://name.org/css-smia#Capability01`)
`name`	`string`	Yes	Name of the capability (e.g., `capability01`)
`category`	`enum`	Yes	`AgentCapability` or `AssetCapability`
`hasLifecycle`	`enum`	Yes	`ASSURANCE`, `OFFER`, or `REQUIREMENT`
`isRealizedBy`	`[ReferenceIRI]`	Yes	Skill IRIs that realize this capability
`assets`	`[Asset]`	Yes	Assets that can perform this capability
`isRestrictedBy`	`[CapabilityConstraint]`	No	Constraints that restrict this capability

Skill schema

Skill¶
Field	Type	Req.	Description
`iri`	`ReferenceIRI`	Yes	Unique ontology IRI identifier
`name`	`string`	Yes	Name of the skill (e.g., `skill01`)
`accessibleThrough`	`[ReferenceIRI]`	No	Skill interface IRIs through which the skill is accessible
`hasParameter`	`[SkillParameter]`	No	Associated skill parameters
`hasImplementationType`	`string`	No	Implementation type (e.g., `OPERATION`, `SPADE_BEHAVIOUR`)

SMIAinstance schema

SMIAinstance¶
Field	Type	Req.	Description
`id`	`ReferenceSMIA`	Yes	SMIA instance identifier (e.g., `agentInstance001`)
`asset`	`Asset`	Yes	Associated asset information
`aasID`	`ReferenceAAS`	Yes	AAS identifier of the instance
`status`	`string`	No	Current status (e.g., `Running`)
`startedTimeStamp`	`integer`	No	Unix timestamp of when the instance started
`smiaVersion`	`string`	No	SMIA software version (e.g., `0.2.3`)

Asset schema

Asset¶
Field	Type	Req.	Description
`id`	`string`	Yes	Asset identifier (e.g., `http://example.com/ids/asset001`)
`kind`	`enum`	Yes	`Type`, `Instance`, or `NotApplicable`
`type`	`ReferenceAAS`	No	AAS reference for the asset

CapabilityConstraint schema

CapabilityConstraint¶
Field	Type	Req.	Description
`iri`	`ReferenceIRI`	Yes	Unique ontology IRI identifier
`name`	`string`	Yes	Name of the constraint (e.g., `capabilityConstraint01`)
`hasCondition`	`enum`	Yes	`INVARIANT`, `PRECONDITION`, or `POSTCONDITION`

SkillParameter schema

SkillParameter¶
Field	Type	Req.	Description
`iri`	`ReferenceIRI`	Yes	Unique ontology IRI identifier
`name`	`string`	Yes	Name of the parameter (e.g., `skillParameter01`)
`hasType`	`enum`	Yes	`INPUT`, `OUTPUT`, or `INOUTPUT`

Usage Examples¶

HTTP requests examples¶

Retrieve all capabilities

curl -X GET "https://<IP>:<PORT>/api/v3/capabilities" \
     -H "Accept: application/json"

Register a new SMIA instance

curl -X POST "https://<IP>:<PORT>/api/v3/smiaInstances" \
     -H "Content-Type: application/json" \
     -d '{
       "id": "agentInstance001",
       "asset": {
         "id": "http://example.com/ids/asset001",
         "kind": "Instance"
       },
       "aasID": "http://example.com/ids/aasElement001",
       "status": "Running",
       "smiaVersion": "0.3.3"
     }'

Encode an IRI for use as a path parameter

curl -X PUT "https://<IP>:<PORT>/api/v3/serialization" \
     -H "Content-Type: application/json" \
     -d '"http://name.org/css-smia#Capability01"'

Check AAS Repository availability

curl -X GET "https://<IP>:<PORT>/api/v3/checkAASRepository?AASRepositoryURL=http://<AAS server IP>:<AAS server PORT>"

FIPA-SMIACL examples¶

Access to SMIA-I KB from an SMIA agent is provided through the SMIA ISM infrastructure component, to ensure decoupling from external services and keep the agent environment fully standardized. The code provided is part of a SPADE behavior, which is responsible for sending messages.