Schema namingstandard

[Sveino]

I like that we use linkML as part of the schema name, e.g. core-equipment.linkml.yaml. However, the use of "-" as space separation is not something we use in CIM. We are following the CamelCase notation, e.g. CoreEquipment (we also use capital letter for class and association and lower case for attributes. At ENTSO-E we use Train-Case for separating topic rather than doc.case and only use the doc for the file extension.

So "core-equipment.linkml.yaml" would become "CoreEquipment-linkedML.yaml". I am not sure if LinkML has any standard for this.

I think it is important that we are consistent and that we have something that will covered all relevant cases. I suggest that we create a description of the name standard that we will be using. This must also cover the "docs":

[bartkl]

Hey Svein,

I'm also about to start a PoC for using LinkML, I'll mail you some more detail. We should definitely learn from each other :).

From what I can tell from the docs, they don't prescribe any naming conventions on files. I think it's best to stick with the conventions already in place. So that would become CoreEquipment-LinkML.yaml, or perhaps CoreEquipment-Profile-LinkML.yaml?

FYI, they do have a linter and recommended rules: https://linkml.io/linkml/schemas/linter.html. But those don't regard file and directory/folder names.

[Sveino]

Thanks. At ENTSO-E we have a set of naming standards. I just did not want to include them in this issue. For profile we are following the w3c standard to use AP (Application Profile).

[tviegut]

Hey @Sveino / @bartkl : Sorry for the long delay!! I go on holiday in a week and have been "burning the midnight oil" as they say since last week (after recovering from Covid I got at the most recent CIM User's Group meetings). :)

As for the naming conventions on the file. The .linkml.yaml is technically not the extension but rather just the '*.yaml portion. and being derived from the last occurrence of the "." The quick background/reason for the additional differentiator (i.e. .linkml) is to differentiate potential builders in CIMTool that generate the same target output file type (*.yaml in this case) but with a format used for purposes. For example, Alex Anderson's new cimgraph Python libraries builder generates *.py files but he has two he needs to produce. Thus his configuration in the new CIMTool 2.1.0 release we pushed out last week:

I can explain in greater detail but if needed since our LinkML output is the first builder targeting *.yaml we can claim first dibs if you want and configure it out of the box as just *.yaml in the CIMTool 2.2.0 release coming out in a couple of weeks. Let me know.

[tviegut]

P.S. I will revisit W3C AP to remind me of what is specified as well.

[Sveino]

First of all, I wanted to check if there are any LinkML naming standard that we need to follow. I am aware that *.yaml is the file extension. And @bartkl confirmed that there are none. In this repository we have not used CamelCase notation, which is the CIM usage. I do not have a problem, in principle to sue "." as separator - however I do prefer to avoid it. That is why we at ENTSO-E is using "-" and "_" in addition to CamelCase notation. See example: https://github.com/Sveino/CGMES-NC/tree/develop/r2.3/ap-voc/rdf
@tviegut if you agree I can make the update in the naming to be aligned with ENTSO-E naming standard. For RDF instant data the naming standard for NC is described in https://eepublicdownloads.entsoe.eu/clean-documents/CIM_documents/Grid_Model_CIM/RCP/Specifications_v2-3/RCP_DES_v2-3-0.pdf line 3013 chapter 8.5.2. We have also documented the schema, but I do not remember now where this is documented.

[bartkl]

I like being consistent with these model suffixes (.linkml and the likes), not making exceptions. It's also more explicit, including when files are shared (and people don't often bother to rename them) it's nice that the file name tells you not only its syntax (YAML in this example), but also its semantics (LinkML here).

But it's your call :)