How-To's
This page presents some instructions, hints and help to accomplish different common use-cases related with the use of Asset Modeling Schemas.
Get the Asset Modeling Schema in LinkML Format
The raw schema specification in LinkML is provided below.
Asset Modeling Schema in LinkML format: iah-base.yaml
Validate Asset Models
You can validate asset models in JSON(-LD) format easily by using JSON Schema validation tools and the JSON Schema provided below.
JSON Schema: iah-base.schema.json
To use the more powerful LinkML validation, you will need the Asset Model Schema
in LinkML format (provided below) and the LinkML tool linkml-validate.
Asset Modeling Schema in LinkML format: iah-base.yaml
For example, to validate the model of a Device in JSON-LD format you can use
the following command:
linkml-validate --target-class Device --schema iah-base.yaml <device-model>.json
Create a derived schema
See the definition of "derived schema" in the corresponding section of the "Concepts" subpage.
Schema template
In order to get as much tools support as possible to create and test derived schemas the CookieCutter template provided by asset_model_schema_template can be used.
Schema skeleton
Simply run cruft create <template> and provide the requested information to get
a schema skeleton with the provided information.
Schema creation
Start editing the schema under src/<schema-name>/schema/<schema-name>.yaml.
Workflow
Follow these steps to create your derived schema:
- Write an example of how you would expect your asset model to look like.
Write it in YAML format in the directory
src/data/examples/valid. - Run the examples validation
make test-examples. You will get some errors since the example does not fit the schema. - Extend the schema to cope with those parts of the model that are not covered by the base schema.
- You might identify some inconsistencies in what you thought would be a good asset model. If that is the case, go back to 1. and fix the model, testing it.
- You will be here if you have a derived schema and at least one working example.
- Ideally add further valid examples to
src/data/examples/validto improve test coverage of your derived schema. - Ideally add invalid examples to
src/data/examples/invalidto have examples of what do DO NOT want to accept in your asset models and ensure that they can be detected as invalid based on the rules defined in the derived schema.
Once you have the schema and some (in)valid examples for testing, you are done (at least for a schema version). Now you can release the schema.
Creation examples
For the creation of the examples following points are to be considered1
(Counter)-Example filename pattern
The example files should follow this pattern <class>-xzy.yaml.
Where <class> is the name of the class being instantiated and xyz is an
index to be able to have multiple instances of the same class.
For example: Device-001.yaml for the first instance of the class Device.
Take existing examples as a reference
The base schema provides enough (counter)-examples to be used as a basis to create examples for the derived schema.
As of now the examples are not publicly available, but can be provided on request and will be made publicly available in the future.
Add new elements progressively
If you add examples with too many new classes or attributes (AKA slots), then it will be more difficult for you to identify the cause for whatever errors might appear.
In general, multiple small examples illustrating individual classes or attributes help better understand the usage of the elements added by the derived schema. It also helps testing of individual elements.
Add realistic examples
Adding realistic examples that might even be created from real assets is meaningfull, no matter if they are big or even huge. Those examples are helpfull to challenge the derived schema with real models and help other people better graps own real assets are being modelled.