From 4a12c320606008112f79b84e79433cab423ec5bf Mon Sep 17 00:00:00 2001 From: Christian Bertsch Date: Fri, 20 Sep 2024 21:26:49 +0200 Subject: [PATCH] add strong recommendation to use reverse-DNS for terminalkinds and variableKinds --- docs/2_4_common_schema.adoc | 15 +++++++-------- docs/2_5_fmu_distribution.adoc | 3 +-- docs/2_6_versioning_layered_standards.adoc | 7 ++++++- docs/7___appendix.adoc | 2 +- 4 files changed, 15 insertions(+), 12 deletions(-) diff --git a/docs/2_4_common_schema.adoc b/docs/2_4_common_schema.adoc index 5fd7940f0..b09f25660 100644 --- a/docs/2_4_common_schema.adoc +++ b/docs/2_4_common_schema.adoc @@ -138,12 +138,9 @@ image::images/schema/Annotations.png[width=80%] Each `Annotation` element contains a required `type` attribute, which contains the namespace for that annotation. The content of the `Annotation` element can be arbitrary XML data, and can make use of XML namespaces and XML schemas for combined validation where appropriate. -The namespace mechanism for the `type` attribute is based on <>: +The namespace mechanism for the `type` attribute is based on <>: The originator of a specification for additional data specifies a domain name under their control as the namespace for the additional data, in order to avoid conflicts due to name collisions. -All namespaces under both the `org.modelica` and `org.fmi-standard` domains are reserved for use in future layered standards. - -_[For example, extensions defined by the Modelica Association might make use of the `org.modelica.fmi` namespace._ -_This could lead to annotations with a `type` attribute of `org.modelica.fmi.something`, and/or extra files under the `extra/org.modelica.ssp.something` sub-directory.]_ +For example this such standardized annotations could be defined by a <>. Annotations are intended to allow structured extensions of the FMI XML files, without creating conflicting extensions, or leaving ambiguities in interpretation. All annotations may safely be ignored by implementations that just implement the base FMI standard. @@ -1894,8 +1891,8 @@ The terminal name must be unique on each level. The normalized string attribute `matchingRule` describes the rules for variable matching in a connection of terminals. As detailed in <>, there are three predefined matching rules: `plug`, `bus`, and `sequence`. Other standards may define new matching rules. -In order to avoid ambiguities and conflicts, rule names must follow the <> of a domain that is controlled by the entity defining the semantics and content of the additional entries. -The rule names beginning with `org.modelica` and `org.fmi-standard` are explicitly reserved for use by layered standards defined by Modelica Association or its own projects (<>). +In order to avoid ambiguities and conflicts, rule names must follow the <> of a domain that is controlled by the entity defining the semantics and content of the additional entries. +Such a rule definition could be part of a <>layered standard>>. .Predefined matching rules. [#table-predefined-matching-rules] @@ -1923,7 +1920,8 @@ An importer should connect terminals only if the number of member variables matc [[terminalKind,`terminalKind`]] The normalized string `terminalKind` is an optional attribute. -Other standards may define terminal kinds. +Other standards may define terminal kinds. +It is strongly recommended to use [[reverse-DNS, reverse domain name notation]] to define a `terminalKind`. It is intended that the `terminalKind` is used to define domain specific member variable sequences, member names and order, or high level restrictions for connections. _[Externally defined terminal kinds should refer to a predefined `matchingRule`, if possible._ @@ -1959,6 +1957,7 @@ Therefore, the `memberName` attribute is required for `plug` and `bus` and must The `memberName` is not required for `matchingRule` `sequence`. The normalized string `variableKind` is used to provide general information about the variable. +It is strongly recommended to use [[reverse-DNS, reverse domain name notation]] to define a `varianbleKind`. This information defines how the connection of this variable has to be implemented (e.g. Kirchhoff's current law or common signal flow). The predefined `variableKind` are: diff --git a/docs/2_5_fmu_distribution.adoc b/docs/2_5_fmu_distribution.adoc index ed1b1270a..0ce49b950 100644 --- a/docs/2_5_fmu_distribution.adoc +++ b/docs/2_5_fmu_distribution.adoc @@ -205,8 +205,7 @@ For more information, please consult the https://modelica.github.io/fmi-guides/m The ZIP archive may contain additional subdirectories within `extra/` that can be used to store additional data, e.g. for the implementation of <>. -In order to avoid ambiguities and conflicts, the names of these subdirectories should use the <> of a domain that is controlled by the entity defining the semantics and content of the additional entries _[(for example `extra/com.example/SimTool/meta.xml` or `extra/org.example.stdname/data.asd`)]_. -The use of subdirectories beginning with `org.modelica` and `org.fmi-standard` is explicitly reserved for use by <> defined by Modelica Association or its own projects (<>), i.e. layered standards defined outside the Modelica Association must not use subdirectory names beginning with these prefixes. +In order to avoid ambiguities and conflicts, the names of these subdirectories should use the <> of a domain that is controlled by the entity defining the semantics and content of the additional entries _[(for example `extra/com.example/SimTool/meta.xml` or `extra/org.example.stdname/data.asd`)]_. It is explicitly allowed for tools and users other than the original creator of an FMU to modify, add or delete entries in the `extra/` directory without affecting the validity of the FMU in all other aspects. Specifically all validation or digital signature schemes used to protect the content of the FMU should take the variability of extra file content into account _[(for example by having separate checksums or signatures for FMU core content and extra content, or not having signatures at all for extra content)]_. diff --git a/docs/2_6_versioning_layered_standards.adoc b/docs/2_6_versioning_layered_standards.adoc index 8130e7835..6ab5fc29d 100644 --- a/docs/2_6_versioning_layered_standards.adoc +++ b/docs/2_6_versioning_layered_standards.adoc @@ -39,7 +39,7 @@ The root element of this XML file shall have the following attributes in the XML |Description |`fmi-ls-name` -|Name, in reverse domain name notation, of the layered standard. +|Name, in <>, of the layered standard. |`fmi-ls-version` |Version of the layered standard. @@ -75,3 +75,8 @@ An example schema that describes the simple example of a manifest above is shown include::examples/fmi_ls_manifest_example_schema.xsd[] ---- +[[LS-reverse-DNS]]Layered standards use the <> of a domain under the control of the organizations that releases the layered standard to reserve namespaces. +All namespaces under both the `org.modelica` and `org.fmi-standard` domains are reserved for use in future layered standards. + +_[For example, extensions defined by the Modelica Association might make use of the `org.modelica.fmi` namespace._ +_This could lead to annotations with a `type` attribute of `org.modelica.fmi.something`, and/or extra files under the `extra/org.modelica.ssp.something` sub-directory.]_ diff --git a/docs/7___appendix.adoc b/docs/7___appendix.adoc index d17e90094..a6d9ae2fd 100644 --- a/docs/7___appendix.adoc +++ b/docs/7___appendix.adoc @@ -178,7 +178,7 @@ The execution of a model partition is triggered by the activation of its Clock. Examples are a mass, stiffness, etc. These parameters are different from <>, because they can be changed independently (according to their <>). -|[[revers-DNS]]_revers domain name notation_ +|[[reverse-DNS]]_revers domain name notation_ A naming convention based on registered domain names, with the order of the components reversed for grouping purposes. |[[reinitialization]]_reinitialization_