2 Structure
This section contains editorial rules on the structure and fixed content of the document and repository:
-
Section 2.1, “Use a generic ASAM specification section structure (ASM-22)”
-
Section 2.2, “Use generic ASAM specification directory structure (ASM-83)”
-
Section 2.4, “Define the complete section structure in the mapping file (ASM-39)”
-
Section 2.5, “Each paragraph shall be uniquely identified (ASM-132)”
-
Section 2.6, “Check to include all needed sections (ASM-27)”
-
Section 2.7, “Include information on normative and informative content (ASM-91)”
-
Section 2.8, “Conventions for mandatory, optional, and conditional content (ASM-133)”
-
Section 2.9, “Include verbal forms for expressions of provisions (ASM-21)”
-
Section 2.11, “Add information about registered standards (ASM-32)”
-
Section 2.12, “List of figures is created automatically (ASM-18)”
-
Section 2.13, “List of tables is created automatically (ASM-19)”
2.1 Use a generic ASAM specification section structure (ASM-22)
-
The section structure of ASAM specifications shall always follow the same pattern.
-
The sequence, headings and the numbering of the first and last sections are fixed.
-
The first section with a specification-specific heading and specification-specific content is the 6th section.
-
The amount of annexes is specification specific. An annex can be normative or informative, which is stated in brackets in the heading of the annex.
-
The specification contains a bibliography.
-
The specification contains a list of figures and a list of tables.
The specification does not contain a list of source code blocks.
The generic section structure and headings are as follows, the text in brackets comment on the content:
Foreword Introduction (specification-specific content) Overview (specification-specific content) Conventions and notations (specification-specific content) Modal verbs (fixed content as defined in rule ASM-21) Normative and informative content (fixed content as defined in rule ASM-91) Deliverables (specification-specific content) 1 Scope (specification-specific content) 2 Normative references (specification-specific content) 3 Terms and definitions (specification-specific content) 4 Abbreviations (specification-specific content) 5 Backward compatibility (specification-specific content) 6 (First specification-specific heading and content) Annexes (specification-specific content) Annex A (normative or informative): (specification-specific heading and content) Annex B (normative or informative): (specification-specific heading and content) Bibliography (specification-specific content) List of figures (content is generated automatically) List of tables (content is generated automatically)
Exceptions
There are no exceptions.
Example
Foreword Introduction Overview Conventions and notations Deliverables 1 Scope 2 Normative references 3 Terms and definitions 4 Abbreviations 5 Backward compatibility 6 General architecture 6.1 File Structure 6.2 Combining Files 6.3 Overview of elements 6.4 Attributes used in the file 6.5 General rules and assumptions 7 Additional data 7.1 User Data 7.2 Including Data 7.3 Using different layout types 7.4 Description of the data quality 8 Coordinate systems 8.1 Coordinate systems overview 8.2 Inertial coordinate systems 8.3 Reference line coordinate systems 8.4 Local coordinate systems 8.5 Summary of all available coordinate systems 8.6 Georeferencing in ASAM OpenDRIVE 9 Geometry 9.1 Road reference line 9.2 Straight line 9.3 Spiral 9.4 Arc 9.5 Generating arbitrary road courses from geometry elements 9.6 Cubic polynom (deprecated) 9.7 Parametric cubic curve 10 Roads 10.1 Properties for road sections and cross section 10.2 Road linkage 10.3 Road type 10.4 Methods of elevation 10.5 Road surface 10.6 Use cases for roads 11 Lanes 11.1 Lane grouping within lane sections 11.2 Lane sections 11.3 Lane offset 11.4 Lane linkage 11.5 Lane properties 11.6 Road markings 11.7 Specific lane rules 12 Junctions 12.1 Common junctions 12.2 Incoming roads 12.3 Connecting roads 12.4 Direct junctions 12.5 Virtual junctions 12.6 Road surface within junctions 12.7 Junction groups 12.8 Controllers for junctions 13 Objects 13.1 Repeating objects 13.2 Object outline 13.3 Object material 13.4 Lane validity for objects 13.5 Access rules to parking spaces 13.6 Object marking 13.7 Object borders 13.8 Object reference 13.9 Tunnels 13.10 Bridges 13.11 Object surface 14 Signals 14.1 Lane validity for signals 14.2 Signal dependency 14.3 Links between signals and objects 14.4 Signal positioning 14.5 Reuse of signal information 14.6 Controllers 15 Railroads 15.1 Railroad tracks 15.2 Switches 15.3 Stations Annexes Annex A (normative): Enumerations Annex B (normative): Data types Bibliography List of figures List of tables
Source
ASAM specific rule.
The following sections contain explanations on how to insert content to the sections of the standard’s structure.
2.1.1 Foreword
-
The Foreword shall be inserted in all parts (documents) of the standard.
-
The Foreword shall be identical in all parts (documents) of the standard.
The section Foreword contains the following paragraphs:
-
About ASAM (use the following fixed content)
ASAM e.V. (Association for Standardization of Automation and Measuring Systems) is a non-profit organization that promotes standardization of tool chains in automotive development and testing. Our members are international car manufacturers, suppliers, tool vendors, engineering service providers, and research institutes. ASAM standards are developed by experts from our member companies and are based on real use cases. ASAM is the legal owner of these standards and is responsible for their distribution and marketing. ASAM standards span a wide range of use cases in automotive development, test, and validation. They define file formats, data models, protocols, and interfaces. The standards enable easy exchange of data and tools within and across tool chains. They are applied worldwide.
-
About the standard (develop specification-specific content)
-
Parts of the standard (develop specification-specific content)
List of the documents containing their document names and corresponding descriptions
Example of a foreword
Code
ASAM e.V. (Association for Standardization of Automation and Measuring Systems) is a non-profit organization that promotes standardization of tool chains in automotive development and testing. Our members are international car manufacturers, suppliers, tool vendors, engineering service providers, and research institutes. ASAM standards are developed by experts from our member companies and are based on real use cases. ASAM is the legal owner of these standards and is responsible for their distribution and marketing. ASAM standards span a wide range of use cases in automotive development, test, and validation. They define file formats, data models, protocols, and interfaces. The standards enable easy exchange of data and tools within and across tool chains. They are applied worldwide. ASAM OpenDRIVE specifies the modeling approach of how to describe static road networks for driving simulation applications using the Extensible Markup Language (XML). Parts of the standard: * Specification + The Specification contains the modeling approach of how to describe static road networks for driving simulation applications.
Result
ASAM e.V. (Association for Standardization of Automation and Measuring Systems) is a non-profit organization that promotes standardization of tool chains in automotive development and testing. Our members are international car manufacturers, suppliers, tool vendors, engineering service providers, and research institutes. ASAM standards are developed by experts from our member companies and are based on real use cases. ASAM is the legal owner of these standards and is responsible for their distribution and marketing.
ASAM standards span a wide range of use cases in automotive development, test, and validation. They define file formats, data models, protocols, and interfaces. The standards enable easy exchange of data and tools within and across tool chains. They are applied worldwide.
ASAM OpenDRIVE specifies the modeling approach of how to describe static road networks for driving simulation applications using the Extensible Markup Language (XML).
Parts of the standard:
-
Specification
The Specification contains the modeling approach of how to describe static road networks for driving simulation applications.
Example how to mention the related parts of a standard
Code
Parts of the standard: * Core specification + The core specification includes a conceptual description of the Testbench and Framework API. * Test Suite User guideline + This guideline provides a set of test cases for the XIL Testbench API to help vendors and users to verify standard conformance of their C# implementations.
Result
Parts of the standard:
-
Core specification
The core specification includes a conceptual description of the Testbench and Framework API. -
Test Suite User guideline
This guideline provides a set of test cases for the XIL Testbench API to help vendors and users to verify standard conformance of their C# implementations.
2.1.2 Introduction
The Introduction section contains the following sub-sections:
-
Overview
-
Conventions and notations
-
Deliverables
2.1.2.1 Overview
The Overview section describes the content of the document and gives information on why the document is needed.
Exceptions
There are no exceptions.
Example
Code
ASAM OpenDRIVE was developed in response to demand for the specification of an exchange format to define static road networks that can be used in driving simulation applications. The ASAM OpenDRIVE Specification specifies the file format for static road network descriptions. The Extensible Markup Language (XML) is used to represent these descriptions. The ASAM OpenDRIVE Specification specifies how to model static road networks. In more detail, it specifies the structure, the sequence, the elements, and values to represent static road networks. Static road networks consist of, for example, roads, lanes, signals, junctions, and objects along the road, for example, traffic islands. The static road networks described in an ASAM OpenDRIVE file can be either artificial or derived from real world data. ASAM OpenDRIVE does not define dynamic content, for example, traffic participants and moving objects. ASAM OpenDRIVE descriptions may contain: * road definitions ** road geometry in plan view ** lateral and elevation profiles of roads ** lanes ** road marks ** signals and their validity for specific roads and lanes ** objects along roads * junctions ** junction types ** connections ** junction areas * junction groups * references to controllers for traffic lights * tram and railway tracks
Result
ASAM OpenDRIVE was developed in response to demand for the specification of an exchange format to define static road networks that can be used in driving simulation applications.
The ASAM OpenDRIVE Specification specifies the file format for static road network descriptions. The Extensible Markup Language (XML) is used to represent these descriptions. The ASAM OpenDRIVE Specification specifies how to model static road networks. In more detail, it specifies the structure, the sequence, the elements, and values to represent static road networks.
Static road networks consist of, for example, roads, lanes, signals, junctions, and objects along the road, for example, traffic islands. The static road networks described in an ASAM OpenDRIVE file can be either artificial or derived from real world data. ASAM OpenDRIVE does not define dynamic content, for example, traffic participants and moving objects.
ASAM OpenDRIVE descriptions may contain:
-
road definitions
-
road geometry in plan view
-
lateral and elevation profiles of roads
-
lanes
-
road marks
-
signals and their validity for specific roads and lanes
-
objects along roads
-
-
junctions
-
junction types
-
connections
-
junction areas
-
-
junction groups
-
references to controllers for traffic lights
-
tram and railway tracks
2.1.3 Scope
The Scope section describes what the document does.
For example, this document
-
specifies …
-
establishes …
-
gives guidelines for …
-
defines terms …
The Scope is written as a series of statements of fact. Do not put any requirements, recommendations or permissions in the Scope.
Exceptions
There are no exceptions.
Example
Code
The ASAM OpenDRIVE Specification explains how the ASAM OpenDRIVE elements are used and explains relationships between elements in the ASAM OpenDRIVE UML model and XSD schemas, for example, roads, lanes, junctions, objects, signals, and railroads.
Result
The ASAM OpenDRIVE Specification explains how the ASAM OpenDRIVE elements are used and explains relationships between elements in the ASAM OpenDRIVE UML model and XSD schemas, for example, roads, lanes, junctions, objects, signals, and railroads.
2.1.4 Normative references
The Normative references section contains the following paragraphs:
-
The Normative references section shall be introduced by the following content:
The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies. Standards referenced in this section are normative in such a way that parts or the whole standard shall be applied when implementing the referenced functionality. Standards referenced in this section shall be cited normatively in the text.
-
List of normative references
Example
Code
The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies. Standards referenced in this section are normative in such a way that parts or the whole standard shall be applied when implementing the referenced functionality. Standards referenced in this section shall be cited normatively in the text. * {GLO_VAR_STA_ASAM_OpenCRG} cite:[ocr] * ISO 3166-1 cite:[iso3166-1] * ISO 3166-2 cite:[iso3166-2] * ISO 8855 cite:[iso8855] * ISO 8601 cite:[iso8601] * ISO 19111 cite:[iso19111] * OMG® UML 2.5.1 cite:[omguml] * W3C XML cite:[w3cxml] * W3C XML Schema cite:[w3cxmlschema]
Result
The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.
Standards referenced in this section are normative in such a way that parts or the whole standard shall be applied when implementing the referenced functionality. Standards referenced in this section shall be cited normatively in the text.
-
ASAM OpenCRG [2]
-
ISO 3166-1 [3]
-
ISO 3166-2 [4]
-
ISO 8855 [5]
-
ISO 8601 [6]
-
ISO 19111 [7]
-
OMG® UML 2.5.1 [8]
-
W3C XML [9]
-
W3C XML Schema [10]
2.1.5 Terms and definitions
The Terms and definitions section shall contain a list of terms with their definitions used in the document. Only terms which are used in the document shall be added. Terms and definitions shall be listed in alphabetical order. Common terms, which a qualified user of the document will already know, should not be defined.
The following structure shall be applied:
3 Terms and definitions
Term
Definition
Term
Definition
The terms shall be developed based on the following rules:
-
The term shall be added in singular form, for example, Static road network.
The definitions shall be developed based on the following rules:
-
The definition shall consist of full sentences that end with a full stop.
-
The definition shall consist of at least one sentence and may consist of additional sentences that support the user to understand the concept.
-
The definition shall be as short as possible.
-
The term shall be mentioned in the description. No synonyms of the term shall be used in the description.
-
The term shall be mentioned in singular or plural form in the description:
-
If an object or concept does occur more than once in the context it is used, use the plural form in the description, for example Controllers are …. The definition shall not start with an article, for example, The controllers are ….
-
If an object or concept does not occur more than once in the context it is used, use the singular form. The definition shall start with an article, for example, A or An, for example, An inertial system is ….
-
-
The description shall answer what the object or concept is. The main characteristics to define the term shall be contained in the definition (mandatory). The definition may be supplemented by information what the object or concept can be used for (optional). Examples may provide information that illustrate the concept (optional). Examples should be written as a statement of fact.
-
The description shall not contain any requirements.
Specifications exist that support technical writers in defining terms and definitions:
-
DIN 2330 - Terminology work - Principles and methods, July 2022
-
ISO 704:2009 – Terminology work – Principles and methods or
-
ISO 860:2007 – Terminology work – Harmonization of concepts and terms
Additional resources regarding terminology can be found here:
Exceptions
There are no exceptions.
Example
Code
Slip road:: A slip road is any road at an intersection that allows to change roads without entering the intersection. Static road network:: A static road network is a collection of connected roads enriched by static objects that do not change during the runtime of a simulation.
Result
- Slip road
-
Any road at an intersection that allows to change roads without entering the intersection.
- Static road network
-
Collection of connected roads enriched by static objects that do not change during runtime of a simulation.
Source
ASAM specific rule.
ISO/IEC Directives, Part 2 Principles and rules for the structure and drafting of ISO and IEC document; 2021.
2.1.6 Abbreviations
The Abbreviations section shall provide a list of all acronyms with their definitions used in the document. Only acronyms that are used in the document shall be added.
The following structure shall be applied:
4 Abbreviations
Abbreviation
Definition
Abbreviation
Definition
Exceptions
There are no exceptions.
Example
Code
ASAM:: Association for Standardization of Automation and Measuring Systems ECU:: Electronic Control Unit
Result
- ASAM
-
Association for Standardization of Automation and Measuring Systems
- ECU
-
Electronic Control Unit
2.1.7 Backward compatibility
When no earlier version of the standard exists, add the following content to this section:
This is the first release of this standard published by ASAM. Therefore, no information about the backward compatibility of this standard has been added to this section.
2.1.8 Specification-specific sections
Specification-specific sections form the main part of any document. These sections define the content of the specification. Requirements shall be written so they can be verified by anyone. The document shall avoid referring to trademarks or companies.
2.1.9 Annexes
Annexes are used to provide additional information to the main body of the document and are developed for several reasons, for example:
-
when the information or table is very long and including it in the main body of the document would distract the user
-
to set apart special types of information, for example, tables, lists, and data
-
to present information regarding a particular use case of the document
Annexes are designated by:
-
The word Annex
-
A space character
-
An identifier for the annex using a capital letter, for example, A
-
A space character
-
The word normative or informative in brackets, for example (normative)
-
A colon
-
A space character
-
An annex specific heading
Example
Annexes Annex A (normative): Enumerations Annex B (normative): Data types
2.1.10 Bibliography
The Bibliography section contains references on standards, literature like books, articles, and so on. All references added in the Normative references section shall also be added to the Bibliography section.
An entry of the Bibliography has the following structure:
<author 1 last name>, <author 1 first name>; <author 2 last name>, <author 2 first name>; <…more authors…>: <title>; <publisher>; <year>; ISBN: <ISBN-13 number>
Example
Bibliography [1] ASAM e.V.: ASAM General Expression; 2017 [2] Jones, Russ; Nye, Adrian: HTML und das World Wide Web; O’Reilly/International Thomson Verlag; 1995; ISBN: 9783930673346
2.2 Use generic ASAM specification directory structure (ASM-83)
The directory structure of a repository of an ASAM specification always follows the same pattern.
The content
folder in the repository contains the core files for the specification.
Each main section has a separate folder which contains the AsciiDoc file with the content of the main section and optional AsciiDoc files with the content of the subsections.
Exceptions
There are no exceptions.
Example
content/ ├── _images/ │ ├── [first folder for images, named like the folder in the repository containing the documentation]/ │ ├── [second folder for images, named like the folder in the repository containing the documentation]/ │ └── ... ├── 00_preface/ │ ├── 00_foreword.adoc │ └── 00_introduction.adoc ├── 01_scope/ │ └── 01_scope.adoc ├── 02_normative_references/ │ └── 02_normative_references.adoc ├── 03_terms_and_definitions/ │ └── 03_terms_and_definitions.adoc ├── 04_abbreviations/ │ └── 04_abbreviations.adoc ├── 05_backward_compatibility/ │ └── 05_backward_compatibility.adoc ├── 06_[first specification-specific main section]/ │ ├── 06_00_[first specification-specific main section].adoc │ ├── 06_01_[first specification-specific sub section].adoc │ ├── 06_01_[first specification-specific sub section].adoc │ └── ... ├── 07_[second specification-specific main section]/ │ ├── 07_00_[second specification-specific main section].adoc │ └── ... ├── ... ├── XX_annexes/ │ ├── [first specification-specific annex]/ │ │ ├── [first specification-specific annex].adoc │ │ └── ... │ └── ... ├── loft/ │ ├── list_of_figures.adoc │ └── list_of_tables.adoc ├── _config.adoc ├── bibliography.bib └── index.adoc
Source
ASAM specific rule.
2.3 Name the mapping file index.adoc (ASM-40)
-
The mapping file index.adoc shall be in the
content
directory of the root directory.
Exceptions
There are no exceptions.
Example
content/ ├── _images/ │ └── ... ├── ... ├── loft/ │ └── ... └── index.adoc
Source
ASAM specific rule.
2.4 Define the complete section structure in the mapping file (ASM-39)
-
Include all sections of all levels of the section structure in the mapping file.
-
Subsections shall not have separate mapping files.
Exceptions
There are no exceptions.
Example
The following example lists the include entries for several sections and subsections in a mapping file.
[preface] include::00_preface/00_foreword.adoc[leveloffset=+1] [preface] include::00_preface/00_introduction.adoc[leveloffset=+1] :sectnums: include::01_scope/01_scope.adoc[leveloffset=+1] include::02_normative_references/02_normative_references.adoc[leveloffset=+1] include::03_terms_and_definitions/03_terms_and_definitions.adoc[leveloffset=+1] include::04_abbreviations/04_abbreviations.adoc[leveloffset=+1] include::05_backward_compatibility/05_backward_compatibility.adoc[leveloffset=+1] include::06_general_architecture/06_00_general_architecture.adoc[leveloffset=+1] include::07_additional_data/07_00_additional_data.adoc[leveloffset=+1] include::08_coordinate_systems/08_00_coordinate_systems.adoc[leveloffset=+1] include::08_coordinate_systems/08_01_coordinate_systems_overview.adoc[leveloffset=+2] include::08_coordinate_systems/08_02_inertial_coordinate_system.adoc[leveloffset=+2] include::08_coordinate_systems/08_04_local_coordinate_system.adoc[leveloffset=+2] include::08_coordinate_systems/08_03_reference_line_coordinate_system.adoc[leveloffset=+2] include::08_coordinate_systems/08_05_summary_coordinate_systems.adoc[leveloffset=+2] include::08_coordinate_systems/08_06_geo_referencing.adoc[leveloffset=+2] ... :sectnums!: == Annexes [appendix] include::16_annexes/enumerations/map_uml_enumerations.adoc[leveloffset=+2] [appendix] include::16_annexes/map_uml_data_types.adoc[leveloffset=+2] [bibliography] == Bibliography bibliography::[] :sectnums!: include::loft/list_of_figures.adoc[leveloffset=+1] :sectnums!: include::loft/list_of_tables.adoc[leveloffset=+1]
Source
ASAM specific rule.
2.5 Each paragraph shall be uniquely identified (ASM-132)
There shall be no text between section levels. In such cases it is necessary to encapsulate the text in a subsection.
Exceptions
There are no exceptions.
Example
No | Yes |
---|---|
6 Quality of standards The ASAM Editorial Guide shall be considered when a specification is written. 6.1 Naming of parts [...] |
6 Quality of standards 6.1 Usage of the ASAM Editorial Guide The ASAM Editorial Guide shall be considered when a specification is written. 6.2 Naming of parts [...] |
Source
ISO/IEC Directives, Part 2 Principles and rules for the structure and drafting of ISO and IEC document; 2021. See section Hanging paragraphs.
2.6 Check to include all needed sections (ASM-27)
-
Check to include all needed sections in the section structure and the mapping file.
-
Remove sections from the repository that are without use in the section structure and mapping file.
Exceptions
There are no exceptions.
Example
There is no example.
Source
ASAM specific rule.
2.7 Include information on normative and informative content (ASM-91)
Place the section on normative and informative content in the Conventions and notations section under the Introduction section in the generic ASAM specification section structure, refer to Section 2.1, “Use a generic ASAM specification section structure (ASM-22)”.
Exceptions
There are no exceptions.
Example
Code
=== Normative and informative content Content in this specification can be normative or informative. The sections listed in <<tab-normative-informative-content>> are normative or informative per definition. Further informative content is shown in table <<tab-informative-text-components>>. [#tab-normative-informative-content] .Normative and informative sections [%header, cols=2*] |=== |Section |Indication |Foreword |Informative |Introduction |Informative |Scope |Normative |Normative references |Informative |Terms and definitions |Normative |Abbreviations |Normative |Backward compatibility |Normative |First to last specification-specific section |Normative |Annexes |Annexes can be normative or informative. The annex heading contains the indication "(normative)" or "(informative)". |Bibliography |Informative |=== All other sections in this specification are normative. [#tab-informative-text-components] .Informative text components [%header, cols="25, 25, 50"] |=== |Text components |Indication |Hints |Notes |Informative |The document shall be usable without notes. |Footnotes |Informative |The document shall be usable without footnotes. |Examples |Informative |The document shall be usable without examples. |Sequence diagrams |Informative |The document shall be usable without sequence diagrams. |=== Notes, footnotes, and examples shall not contain requirements or any information considered indispensable for the use of the document, for example, instructions or permission.
Result
Normative and informative content
Content in this specification can be normative or informative. The sections listed in Table 11 are normative or informative per definition. Further informative content is shown in table Table 12.
Section | Indication |
---|---|
Foreword |
Informative |
Introduction |
Informative |
Scope |
Normative |
Normative references |
Informative |
Terms and definitions |
Normative |
Abbreviations |
Normative |
Backward compatibility |
Normative |
First specification-specific section |
Normative |
Annexes |
Annexes can be normative or informative. The annex heading contains the indication "(normative)" or "(informative)". |
Bibliography |
Informative |
All other sections in this specification are normative.
Text components | Indication | Hints |
---|---|---|
Notes |
Informative |
The document shall be usable without notes. |
Footnotes |
Informative |
The document shall be usable without footnotes. |
Examples |
Informative |
The document shall be usable without examples. |
Sequence diagrams |
Informative |
The document shall be usable without sequence diagrams. |
Notes, footnotes, and examples shall not contain requirements or any information considered indispensable for the use of the document, for example, instructions or permission.
Source
ASAM specific rule.
2.8 Conventions for mandatory, optional, and conditional content (ASM-133)
For exchange of products it is necessary that mandatory, optional, and conditional functionalities in a standard are classified. The condition shall be stated.
A standard compliant implementation shall support all mandatory functionalities.
In the case of an optional functionality, it might be required to define if the functionality must be implemented, for example, when looking at the implementation for a server or a client.
Exceptions
There are no exceptions.
Example
In case of an API it is necessary to define which interfaces, methods, and attributes shall be implemented. If necessary, the definition shall state if the implementation is relevant for servers or clients.
Attribute | Type | Convention | Description |
---|---|---|---|
id |
string |
Mandatory |
Unique identifier of a value. |
data |
AnyValue |
Mandatory |
The value of the data. |
errors |
DataError[] |
Conditional |
Condition: Only set, if the value data represents an error and this attribute describes the error more precisely. |
shema |
OpenAPI Schema |
Conditional |
Schema for the data. |
translation_id |
string |
Optional |
Identifier for translating the value identifier (id). |
Source
ASAM specific rule.
2.9 Include verbal forms for expressions of provisions (ASM-21)
Use and update the following section with the table of verbal forms for expressions of provisions in a specification document.
Place the modal verbs section in the Conventions and notations section under the Introduction section in the generic ASAM specification section structure, refer to Section 2.1, “Use a generic ASAM specification section structure (ASM-22)”.
Exceptions
There are no exceptions.
Example
Code
[#sec-modal-verbs] === Modal verbs To ensure compliance with the {THIS_STANDARD} specification, users need to be able to distinguish between requirements, recommendations, permissions, possibilities and capabilities, and external constraints. [#tab-modal-verbs] .Verbal forms for expressions of provisions [%header, cols="20, 15, 65"] |=== |Provision |Verbal form |Definition |Requirement |shall, shall not |A requirement conveys objectively verifiable criteria to be fulfilled and from which no deviation is permitted if conformance with the document is to be claimed. |Recommendation |should, should not |A recommendation conveys a suggested possible choice or course of action deemed to be particularly suitable without necessarily mentioning or excluding others. |Permission |may |A permission conveys consent or liberty (or opportunity) to do something. |Possibility and capability |can, cannot |A possibility conveys expected or conceivable material, physical or causal outcome. + A capability conveys the ability, fitness, or quality necessary to do or achieve a specified thing. |External constraint |must |An external constraint or obligation on the user of the document, for example laws of nature or particular conditions existing in some countries or regions, that is not stated as a provision of the document. External constraints are not requirements of the document. They are given for the information of the user. |===
Result
Modal verbs
To ensure compliance with the ASAM OpenDRIVE Specification, users need to be able to distinguish between requirements, recommendations, permissions, possibilities and capabilities, and external constraints.
The following rules for using modal verbs apply:
Provision | Verbal form | Definition |
---|---|---|
Requirement |
shall, shall not |
A requirement conveys objectively verifiable criteria to be fulfilled and from which no deviation is permitted if conformance with the document is to be claimed. |
Recommendation |
should, should not |
A recommendation conveys a suggested possible choice or course of action deemed to be particularly suitable without necessarily mentioning or excluding others. |
Permission |
may |
A permission conveys consent or liberty (or opportunity) to do something. |
Possibility and capability |
can, cannot |
A possibility conveys expected or conceivable material, physical or causal outcome. |
External constraint |
must |
An external constraint or obligation on the user of the document, for example laws of nature or particular conditions existing in some countries or regions, that is not stated as a provision of the document. External constraints are not requirements of the document. They are given for the information of the user. |
Source
ASAM specific rule.
2.10 Use the standard disclaimer (ASM-31)
2.10.1 Restricted domains
Include the following standard disclaimer for the ASAM standards of restricted domains:
Disclaimer
This document is the copyrighted property of ASAM e.V. Any use is limited to the scope described in the license terms. The license terms can be viewed at www.asam.net/license |
Exceptions
There are no exceptions.
Example
Code
[IMPORTANT] .Disclaimer ==== This document is the copyrighted property of ASAM e.V. Any use is limited to the scope described in the license terms. The license terms can be viewed at https://www.asam.net/license[www.asam.net/license] ====
2.10.2 Unrestricted domains
Include the following standard disclaimer for the ASAM standards of unrestricted domains:
Disclaimer
This document is the copyrighted property of ASAM e.V. In alteration to the regular license terms, ASAM allows unrestricted distribution of this standard. §2 (1) of ASAM’s regular license terms is therefore substituted by the following clause: "The licensor grants everyone a basic, non-exclusive and unlimited license to use the standard {THIS_STANDARD}". |
Exceptions
There are no exceptions.
Example
Code
[IMPORTANT] .Disclaimer ==== This document is the copyrighted property of ASAM e.V. In alteration to the regular https://www.asam.net/license[license terms], ASAM allows unrestricted distribution of this standard. §2 (1) of ASAM's regular https://www.asam.net/license[license terms] is therefore substituted by the following clause: "The licensor grants everyone a basic, non-exclusive and unlimited license to use the standard {THIS_STANDARD}". ====
Source
ASAM specific rule.
2.11 Add information about registered standards (ASM-32)
-
Information shall be added if a standard is registered (see external link).
Exceptions
There are no exceptions.
Example
Code
<Official name of the standard> is a registered trade mark of ASAM e.V.
Result
ASAM OpenDRIVE is a registered trade mark of ASAM e.V.
Source
ASAM specific rule.