search

oasis-open / tosca-community-contributions

OASIS TC Open Repository: Manages TOSCA profiles, tests, and templates that are maintained by the TOSCA community. They are intended to be used as examples to help developers get started with TOSCA and to test compliance of TOSCA implementations with the standard.
https://github.com/oasis-open/tosca-community-contributions
Apache License 2.0
39 stars 25 forks source link

TOSCA files #112

Open tliron opened 2 years ago

tliron commented 2 years ago

This is a proposal to properly document what a TOSCA file is and its rules, especially as they relate to imports.

A TOSCA file is a YAML file that can be:

a) the root of a service template (it has a topology_template) section b) the root of a profile, or c) an importable file

Rules:

  1. All TOSCA files must have a tosca_definitions_version keyname (and the file must be parsed in this version, no matter what is importing it)
  2. Some TOSCA parsers might be able to support multiple versions of TOSCA. This requires discussion in the context of imports. Could a file import a higher version of TOSCA? How do we handle differences in the metamodel?
  3. Each file can optionally have an about keyname that describes that particular file (this is a separate proposal, #113)
  4. If a file has a dsl_definitions keyname then those anchors are only usable in that file. (This is a YAML parser limitation, but worth pointing out.)
  5. If the root file has a topology_template then it and only it can have that keyname (no other imports, at any depth of import nesting, can have it; we do not support "merging" a topology template distributed across files).

Let's discuss!

pmjordan commented 2 years ago

There are lots of clauses which a unit may optionally have, the proposed 'about' clause is just one of them. IMO the defintion would be better if item 3. were omitted.

The word 'document' might be more expressive than the word 'unit'.

Clause 4 as currently written would allow a root unit which does not have a topology_template to import two or more units which each contain a topology_template; I doubt that is the intent.

lauwers commented 2 years ago

I'm not a big fan of the term "unit". As far as I know, it is a term that is not used anywhere else in the industry, and I believe it would create more confusion than it solves. Instead, we clearly state that a "TOSCA File" is a YAML file that contains TOSCA statements, a TOSCA Artifact File contains artifacts referenced in TOSCA Files, and CSAR Files are how we package TOSCA Files, TOSCA Artifacts, and anything necessary for deployment.

lauwers commented 2 years ago

In the Ubicity implementation, I don't require that the 'topology_template' must be specified in the "root" file. It can be specified in an imported file, as long as there is only such statement.

tliron commented 2 years ago

How about "module"? That's used fairly commonly in how programming languages refer to their imported ... things. What's special about "modules" in TOSCA is that they do not have independent namespaces, as we assume a root namespace applies to all of them (when translated into a global namespace).

@pmjordan's proposal of "document" is also not bad.

lauwers commented 2 years ago

OK, let's try to decide on Tuesday.

tliron commented 2 years ago

I've updated the original proposal to use the word "file"