Simplify documentation of datamodels and usage of plugins #977
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
francescalb
changed the title
|
Ø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). |
francescalb
changed the title
Comment on lines
+50
to
+53
| 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.
Suggested change
| 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. |
Comment on lines
+56
to
+65
| 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.
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.
Suggested change
| unit: unit # can be ommitted, not relevant with type ref | |
| unit: unit # Can be ommitted if the property has no unit |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.