CDDL Module Structure

Module superstructure

Compatibility:: bidirectional (both backward and forward)

Originally, CDDL was used for small data models that could be expressed in a few lines. As the size of data models that need to be expressed in CDDL has increased, the need to modularize and re-use components is increasing. CDDL as documented in (basic CDDL) has been designed with a crude form of composition: Concatenating a number of CDDL snippets creates a valid CDDL data model unless there is a name collision (identical redefinition is allowed to facilitate this approach). With larger models, managing the name space to avoid collisions becomes more pressing. In CDDL's original composition model, the knowledge which CDDL snippets need to be concatenated in order to obtain the desired data model lives entirely outside the CDDL snippets. With the module structure defined in the present document, rules are packaged as modules and referenced from other modules, providing methods for control of namespace pollution. Further work may be expended on unambiguous referencing into evolving specifications ("versioning") and selection of alternatives (as was emulated with snippets in . Note that one approach for expressing variants is demonstrated in based on ). Potential further work is outlined in Sections and of .

Compatibility To achieve the module structure in a way that is friendly to existing environments that operate with CDDL and basic CDDL implementations, we add a super-syntax (similar to the way pragmas are often added to a language), by carrying them in what is parsed as comments in basic CDDL. This enables each module source file to be basic CDDL on its own (possibly needing to add some rule definitions imported from other source files).

Namespacing When importing rules from other modules, there is the potential for name collisions. This is exacerbated when the modules evolve, which may lead to the introduction of a name into an imported module that is also used (likely in a different way) in the importing module. To be able to manage names in such a way that collisions can be avoided, we introduce means to prepend a prefix to the names of rules being imported: the "as" clause.

"Directives", the "module" This specification introduces directives into CDDL. A single CDDL file becomes a module by processing the (zero or more) directives in it. The semantics of the module are independent of the module(s) using it, however, importing a module may involve transforming its rule names into a new namespace (). Directives look like comments in basic CDDL, so they do not interfere with forward compatibility. In the CDDL module structure, lines starting with the prefix ;# are parsed as directives.

Naming and Finding Modules We assume that module names are filenames taken from one of several source directories available to the CDDL module structure processor via the environment. This avoids the need to nail down brittle pathnames or (partial?) URIs into the CDDL files. The exact way how these source directories and possibly a precedence between them are established is intentionally not fully defined in this specification; it is expected that this will be specified in the context of the models just as the way they are intended to be used will be. (A more formal structure may follow later.) In the module structure implementation that is part of the CDDL Tool described in , the set of sources is determined from an environment variable, CDDL_INCLUDE_PATH, which is modeled after usual command-line search paths. It is a colon-separated list of pathnames to directories, with one special feature: an empty element points to the tool's own collection. This collection contains fragments of extracted CDDL from published RFCs, using names such as rfc9052. (Future versions might augment this with Web extractors and/or ways to extract CDDL modules from github and from Internet-Drafts; see for some design considerations.) The default CDDL_INCLUDE_PATH is: That is: files are found in the current directory (.) and, if not found there, cddlc’s collection. In the examples following, a cddlc command line will be shown (starting with an isolated $ sign) with the module-structured CDDL input; the resulting basic CDDL will be shown separately.

Basic Set of Directives Two groups of directives are defined at this point:

include, which includes all the rules from a module (which includes the ones imported/included there, transitively), or specific explicitly selected rules (clause ending in "from");
import, which includes only those rules from the module that are referenced, implicitly or explicitly (clause ending in "from"), including the rules that are referenced from these rules, transitively.

The include function is more useful for composing a single model from parts controlled by one author, while the import function is more about treating a module as a library: The way an import works is shown by this simple example: This results in the following CDDL 1.0 specification: tstr / int, ? 2 => bstr, ? 3 => tstr / int, ? 4 => [+ tstr / int], ? 5 => bstr, * label => values, } label = int / tstr values = any ]]> This is appropriate for using libraries that are well known to the importing specification. However, if it is not acceptable that the library can pollute the namespace of the importing module, the import directive can specify a namespace prefix ("as" clause): This results in the following CDDL 1.0 specification: tstr / int, ? 2 => bstr, ? 3 => tstr / int, ? 4 => [+ tstr / int], ? 5 => bstr, * cose.label => cose.values, } cose.label = int / tstr cose.values = any ]]> Note how the imported names are prefixed with cose. as specified in the import directive, but CDDL prelude () names such as tstr and any are not.

Explicit selection of names Both import and include directives can be augmented by an explicit mentioning of rule names (clause ending in "from").

include Starting with include: values} ;# include label, values from rfc9052 ]]> With include, only exactly the rules mentioned are included: values} label = int / tstr values = any ]]> The module from which rules are explicitly imported can be namespaced: values} ;# include cose.label, cose.values from rfc9052 as cose ]]> Again, only exactly the rules mentioned are included: values} cose.label = int / tstr cose.values = any ]]>

import Both examples would work exactly the same with import, as the included rules do not reference anything else from the included module. An import however also draws in the transitive closure of the rules referenced: The transitive closure of the rules mentioned is included: cose.empty_or_serialized_map} cose.empty_or_serialized_map = bstr .cbor cose.header_map / bstr .size 0 cose.header_map = { cose.Generic_Headers, * cose.label => cose.values, } cose.Generic_Headers = ( ? 1 => int / tstr, ? 2 => [+ cose.label], ? 3 => tstr / int, ? 4 => bstr, ? (5 => bstr // 6 => bstr), ) cose.label = int / tstr cose.values = any ]]> The import statement can also request an alias for an imported name: Note how an additional rule provides an alias for empty_or_serialized_map that does not have the namespace prefix: cose.empty_or_serialized_map} empty_or_serialized_map = cose.empty_or_serialized_map cose.empty_or_serialized_map = bstr .cbor cose.header_map / bstr .size 0 cose.header_map = { cose.Generic_Headers, * cose.label => cose.values, } cose.Generic_Headers = ( ? 1 => int / tstr, ? 2 => [+ cose.label], ? 3 => tstr / int, ? 4 => bstr, ? (5 => bstr // 6 => bstr), ) cose.label = int / tstr cose.values = any ]]>

Tool Support for Command-Line Control Tools may provide a convenient way to initiate the processing of directives from the command line. A tool may provide a way to root the module tree from the command line: The command line argument -icose=rfc9052 is a shortcut for Together with the start rule name, cose.COSE_Key, this results in the following CDDL 1.0 specification: tstr / int, ? 2 => bstr, ? 3 => tstr / int, ? 4 => [+ tstr / int], ? 5 => bstr, * cose.label => cose.values, } cose.label = int / tstr cose.values = any ]]> In other words, the module synthesized from the command line had an empty CDDL file, which therefore was not provided (no – on the command line).