Proposal for changes to namespaces and imports

[Tal Liron <tliron@redhat.com>]

I'll summarize what I proposed in the ad hoc meeting, which is a continuation of the older email threads.

URL KEYWORD

I propose to change the imports "file" keyword to "url" and indeed define it as a URL which defaults to the "file::" scheme. Examples:

# Short notation supported

imports:

- types/mytypes.yaml

# Long notation

imports:

- url: types/mytypes.yaml

# Relative file

imports:

- url: ../mytypes.yaml

# Absolute URL with scheme

imports:

- url: https://myorg.org/tosca/types/mytypes.yaml

# Root file

imports:

- url: /base.yaml

URL is either relative ("file" scheme) or absolute. Chris proposed that the file root should be the root of the CSAR if the current file is in a CSAR (in that final example).

PROFILE KEYWORD

I then propose the addition of an imports "profile" keyword. One and only one of "url" or "profile" keywords must be specified. Example:

imports:

- profile: myprofilename

The profile names exist entirely separately from the world of URLs and are arbitrary strings. How would implementations know where to fetch these profiles? That's up to them, and there is of course no guarantee that the profile would be successfully imported everywhere.

However, profile names can be provided by profile writers via the global "profile" keyword (replacing the old "namespace" keyword), e.g.:

tosca_definitions_version: tosca_2.0

profile: myprofilename

So, this does ensure that across implementations the same imports would likely work (again, no guarantee). This keyword is used as a kind of metadata for the intended name of the profile if registered in some kind of internal repository so that it would match the value of the imports "profile" keyword. Technically there is no restriction on the value of this string, but I propose we encourage a Java-style reverse-domain notation with version as conventional, e.g:

profile: org.oasis-open.tosca.simple:2.1

profile: io.kubernetes:1.18

CANONICAL TYPE NAMES

I propose that we introduce the concept of "canonical type names" that are defined as a combination of the profile name (if exists) plus the bare type name. Finding the profile name for a given type means going back in the import try until one hits the first "profile" keyword. (Profiles can import other profiles but do not change the profile name of whatever they import.)

This does mean that if a single file does not define a profile name and is imported by two different profiles in fact its specific type would have two different canonical names. That is fine! Conceptually these are two different types despite being identical in structure.

I think it could be useful to sometimes refer to types by their canonical type name in TOSCA, in order to avoid any kind of ambiguity, via some kind of special notation. Chris disagrees but I think it's worth discussing the pros and cons more.

NAMESPACE KEYWORD

I propose to change the import "namespace_prefix" keyword to be just "namespace". If "namespace" is not specified then all the types will be imported into the "root" unnamed namespace. Name ambiguities should of course be reported by parsers. Example:

imports:

- url: types/mytypes.yaml

 namespace: my

topology_template:

 node_templates:

ÂÂÂ mynode:

ÂÂÂÂÂ type: my:MyType

(So, now we no longer have confusion regarding what a "namespace" is. It's used only for literal reference to imported names. The "profile name" is something entirely different.)

MERGING OR NESTING?

We also need to discuss how namespaces work with an import tree. I propose that namespaces are merged, not nested. Example:

mytypes.yaml

------------

imports:

- profile: io.kubernetes:1.18

 namespace: k

node_types:

 MyNode: {}

 SuperPod:

ÂÂÂ derived_from: k:Pod

main.yaml

---------

imports:

- url: mytypes.yaml

 namespace: my

topology_template:

 node_templates:

ÂÂÂ mynode:

ÂÂÂÂÂ type: my:MyType

ÂÂÂ pod:

ÂÂÂÂÂ type: k:Pod

The important part is at the end, when the Pod refers to "k:Pod". That "k" namespace was created in mytypes.yaml and is merged into main.yaml.

Another approach could be nesting, so that we would have to refer to it as "my:k:Pod". To me that looks clumsy and unnatural, and it also has no major advantages.