The rule UID can be defined in a unique form, so it can be identified and optionally encapsulate the identity and the revision of the rule that is taken into consideration.
In the design of such UID we must take into consideration the following:
- even if the majority of rules are defined by ASAM, there is nothing that prevents third-party to define their own rules (concept of emanating entity)
- rules can apply to FRAMEWORK (e.g., existence of a file, extension of the file, etc.), OpenDRIVE and OpenSCENARIO. There is nothing that prevents the creation of rules for other standards such as, e.g., OTX. The UID should allow future extensions (concept of reference standard)
- a rule can be mandated directly from the standard, or may be implemented in the checker, to be proposed in the standard. Furthermore a rule can apply only to certain version of the standard (concept of definition setting)
- a rule can optionally be part of a certain group or subgroup of rules that refer to the same baseline concepts (concept of rule-set)
- rules must be addressable inside their definition setting or rule-set (concept of name)
- rules can evolve in time (for example in description) but in general the underline concept of a rule should always hold. Nevertheless it is advisable to maintain a version for the rule. It should be debated if the version should be included or not, but the proposal tries to be flexible enough to include this information (concept of version)
In general, rules will be queried: querying should allow to move from generic to specific information. A query that can be performed directly on UID may be advisable.
The proposal considers a notation in wich concept are separated by a well defined character, like :
Lets start with an example for a very complete UID, and lets break down its content. For the reference example a rule listed in the subsection Rules of one of the ASAM Standards for OpenDRIVE is used. This subsections were introduced for the first in the revision 1.6 of the standard.
ASAM OpenDRIVE Standard 1.6.0, Chapter 7.2 - Road Reference Line, subsection Rule, first point:
Each road shall have a reference line
Starting from the initial concept of emanating entity, it is possible to use this notation to actually give an UID for the quoted rule:
- emanating entity: ASAM
net.asam - reference standard: OpenDRIVE
xodr - definition settings: as a proposal to be discussed, one can consider to use the version of the standard in which the rule firstly appeared, in this case
1.6.0 - ruleset: Road Planview Geometry definitions
road.planview.geometry - name: a name. It can be arbitrary chosen, e.g.:
rl-existsfor a more descriptive name, orr-001for something more standardisable. - version: it is advisable to use something simple, like a number
The complete UID would be something like:
asam.net:xodr:1.6.0:road.planview.geometry.rl-exists:1
-------- ---- ----- ---------------------- --------- -
| | | | | |
entitity | version | name rule-version (optional, simplified)
standard rule-set (name is always last in rulest dot-notation)
Regarding the validation schema itself, only the the first concept is fully required. Entities that are not ASAM itself are not required to declare rule with the concepts stated above. The schema is a formalism which is required only for rule under asam.net:*. To be noticed that the proposed schema suggests implicitly a hierarchy of concepts, from the broadest one (entity) to the most specific one (rule version).
Example: if my company has defined it's own rules, they may be something like:
com.antemotion.rule-1andcom.antemotion.rule-2and the UID should be considered valid.
Example: the workgroup ASAM for OpenDRIVE shall create all UIDs for the rules under the reverse domain name that starts with
net.asam.xodr.
- entity:
asam.net - standard:
- Framework:
asam.net:qc - OpenDRIVE:
asam.net:xodr- v1.4.0:
asam.net:xodr:1.4.0 - v1.5.0:
asam.net:xodr:1.5.0 - v1.6.0:
asam.net:xodr:1.6.0 - v1.6.1:
asam.net:xodr:1.6.1 - v1.7.0:
asam.net:xodr:1.7.0 - v1.8.0:
asam.net:xodr:1.8.0 - Future v2?:
asam.net:xodr:2.0.0 - Rules that are part only of Quality Checker and are proposed for insertion in standard:
asam.net:xodr:future
- v1.4.0:
- OpenSCENARIO XML:
asam.net:xosc- v1.0.0:
asam.net:xosc:1.0.0 - v1.1.0:
asam.net:xosc:1.1.0 - v1.1.1:
asam.net:xosc:1.1.1 - v1.2.0:
asam.net:xosc:1.2.0
- v1.0.0:
- OpenSCENARIO DSL?:
asam.net:osc- v2.0.0?:
asam.net:osc:2.0.0
- v2.0.0?:
- Framework:
All the other sub-concepts for ASAM are subject to discussion during actual definition of rules.
The proposed formalism allow to perform query on rules (or set of rules) using UNIX style wildcards notation (python fnmatch). In the implementation of the checker framework is advisable that the end-user can enable or disable check based on the UID of the rules that the check verifies. This approach pushes agnostic approaches for check selection (i.e., for checker framework different with respect to the one offered by the ASAM OS project).
Examples:
- select all the OpenDRIVE geometrical rules that are not in version 2 of the standard:
asam.net:xodr:1.?.0:*geometry.*matchesasam.net:xodr:1.6.0:road.planview.geometry.rl-exists:1 - select all the OpenDRIVE geometrical rules that are in version 1.6 and 1.7 of the standard:
asam.net:xodr:1.[67].0:*geometry.*matchesasam.not:xodr:1.6.0:road.planview.geometry.rl-exists:1but does not matchasam.net:xodr:1.8.0:road.planview.geometry.rl-exists:1
The main task inside the OpenDRIVE QC subgroup is to define the best practice for naming OpenDRIVE rules, taking for granted the root domains asam.net:xodr:?.?.?. The concepts that should be defined are:
- rule-sets: there are different alternatives for defining the rule-set:
- OpenDRIVE uses XML as main language, and the majority of the rule may express a hierarchy that strongly resemble the hierarchy of the XML schema of opendrive (i.e., xml elements
t_road > t_road_type > t_road_type_speedmay be defined asroad.type.speed_typesubdomain). Other special cases should be discussed. - Chapter inside standard description may be used (discouraged by members of the workgroup)
- Special definitions may be defined by the subgroups for each rule
- OpenDRIVE uses XML as main language, and the majority of the rule may express a hierarchy that strongly resemble the hierarchy of the XML schema of opendrive (i.e., xml elements
- rule naming convention: in general is advisable to use a short string name that describes what the rule is doing. Alternatively, the rule can be numbered based upon definition order. As a final alternative, rule name can be generated as short sha256 (first 7 characters of sha256) of the description field.
-
The UID is very long. It can be a problem to search for it efficiently in Databases (it is not an integral type nor has a constant size) or may raise Path Too Long error (I'm looking at you Windows).
The length of the UID comes with its advantages. It is possible to understand many of the information of a rule only by looking at its uid, even without reading the rule description. Furthermore, UID can be navigated much like a file system. It is possible to change base location using both an absolute or a relative reference (relative reference may start with a
.character), or list all the sub-uid from that location.The total number of rules is low enough that using this string in query for databases is a non-issue in terms of efficiency. In case specific implementations needs a faster query strategy, a checksum of the original UID can be used as primary key (integral type with constant size).
Using a directory structure that mimics the structure of the uid, or using the entire uid for filenames can reach rapidly numbers that triggers the Path too long error in windows. This must be taken in consideration in all implementations (even in documenting the project)
-
The version of the standard in the UID may create confusion
This is the biggest weak point in the proposal. There are two main confusing situation:
- from an end user perspective, request/remove the check for a certain rule requires a knowledge of the first version of the standard in which the rule appeared. Must be taken into consideration that to actually validate a rule, its uid is not sufficient. Indside the definition of the rule there will be a range of version on which the rule can be validated, and the current file should be inside that range.
- from a developer perspective may be difficult to undestand which rule id insert in a checker.
Alongside this confusion there is a great advantage: if something changes drammatically between two standards, there can be two different rule id (that have the same rule-set and rule name) relative to two different rules. The different part is the version of the standard in the UID (
asam.net:xoder:1.6.0:road.planview.geometry.rl-exists:1 != asam.net:xoder:1.8.0:road.planview.geometry.rl-exists:1). The probability that this will happen is quite low. -
Is a simple counter for versions enough, or do we need a semantic versioning?
No. We can also use a simple counter in place of semantic versioning. Please notice that the inclusion of the version of the rule in the uid is still open for discussion
Thank you very much for your proposal.
I personally like the structure of the second version better.
Also, the simplified rule version helps with making it more distinct from the xodr version.
I have one suggestion in reagards to the "rule-set".
What do you think of using the chapter headlines of the OpenDrive document instead of the structure of the the xml file?
i.e. instead of:
it would look a little something like this:
This might make it more easy to find the rule definition in the standard.
But if future versions of the standard have a completely different chapter structure / different headlines it could cause problems.