-
Notifications
You must be signed in to change notification settings - Fork 6
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Simplify documentation of datamodels and usage of plugins #977
base: master
Are you sure you want to change the base?
Conversation
Ønsker du helt å slette avsnittet om datamodeller eller bare forbedre det? |
Also removed many different ways of doing it so that we rather show one and have people use that
No, I had forgotten to push the file. However, I think it smart to now have many different examples which are confusing and rather provide the preferred one (yaml, newer version). |
First we have "uri" identifying the entity, and a human description. | ||
Then comes "dimensions".In this case one dimension named "N", which is the number of skills the person has. | ||
Finally we have the properties; "name", "age" and "skills". | ||
We see that "name" is represented as a string, "age" as a floating point number with unit years and "skills" as an array of strings, one for each skill. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
First we have "uri" identifying the entity, and a human description. | |
Then comes "dimensions".In this case one dimension named "N", which is the number of skills the person has. | |
Finally we have the properties; "name", "age" and "skills". | |
We see that "name" is represented as a string, "age" as a floating point number with unit years and "skills" as an array of strings, one for each skill. | |
The keywords in the datamodel has the following meaning: | |
* `uri`: A URI that uniquely identifies the datamodel. | |
* `description`: A human description that describes what this datamodel represents. | |
* `dimensions`: Dimensions of the properties (referred to by the property shape). Properties can have the same dimensions, but not necessarily. Each dimension is described by: | |
- name of the dimension | |
- a human description of the dimension | |
In the above example there is one dimension with name "N" and description "Number of skills." | |
* `properties`: Sub-parts of the datamodel that describe the individual data fields. A property has a name and is further specified by the following keywords: | |
- `description`: Human description of the property. | |
- `type`: Data type of the property. Ex: "blob5", "boolean", "uint", "int32", "string", "string10", "ref", ... | |
- `$ref`: Optional. URI of a sub-datamodel. Only used if type is "ref". | |
- `unit`: Optional. The unit. Ex: "kg", "km/h", ... Can be omitted if the property has no unit. | |
- `shape`: Optional. Describe the dimensionality of the property as a list of dimension names. Ex: `[N]`. Can be omitted if the property is a scalar. | |
The datamodel above has three properties; "name", "age" and "skills". We see that "name" is represented as a string, "age" as a floating point number with unit years and "skills" as an array of strings, one for each skill. |
dlite-validate | ||
============== | ||
The dlite-validate tool can be used to check if a specific representation (in a file) is a valid DLite datamodel | ||
|
||
This can be run as follows | ||
```bash | ||
dlite-validate filename.yaml # or json | ||
``` | ||
|
||
It will then return a list of errors if it is not a valid representation. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this should be moved to doc/user_guide/tools.md
. But it would be great with a note here saying that datamodels can be validated using the dlite_validate
tool, with a reference to the correct section in doc/user_guide/tools.md
.
Co-authored-by: Jesper Friis <[email protected]>
Co-authored-by: Jesper Friis <[email protected]>
Co-authored-by: Jesper Friis <[email protected]>
Co-authored-by: Jesper Friis <[email protected]>
Co-authored-by: Jesper Friis <[email protected]>
Co-authored-by: Jesper Friis <[email protected]>
Co-authored-by: Jesper Friis <[email protected]>
name_of_property1: | ||
description: What is this property | ||
type: ref # Can be any on string, float, double, int, ref .... | ||
unit: unit # can be ommitted, not relevant with type ref |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
unit: unit # can be ommitted, not relevant with type ref | |
unit: unit # Can be ommitted if the property has no unit |
Description
I keep having problems with creating my own plugins and datamodels, and there
are so many inconsistent examples around.
I try here to clarify some of the things and add a small section on how to make entities, that is easy to find.
Type of change
Checklist for the reviewer
This checklist should be used as a help for the reviewer.