"about" keyname

[tliron]

Every TOSCA file (see #112) can have an about keyname with the following keys, all optional:

• short_description (no newlines)
• long_description (standardize on Markdown?)
• version (semver, for this particular unit)
• project_name
• project_version (not semver, because it should match the project's versioning system)
• project_url (e.g. homepage)
• platform (e.g. orchestrator name, if intended to be used in a specific environment)
• platform_version (not semver, because it should match the platform's versioning system)
• platform_url (e.g. homepage)
• author_names (string or list of string)
• author_emails (string or list of string)
• license_name (including version, see this)
• license_url (can be a relative URL, relative to this unit)
• documentation_url (can be a relative URL, relative to this unit)
• vcs_repository_url (absolute URL)
• ...

[lauwers]

A couple of comments:

• A TOSCA file already supports a 'description' keyword at the top level. Would the 'description' keywords in the about section replace the top-level keyword?
• I'm not in favor of defining the intended platform in the about section. In theory, TOSCA files should be platform independent. If they can only be used with a specific orchestrator then perhaps that is better expressed using metadata?
• Can different TOSCA files have the same project name (i.e. can the project name be used to uniquely identify a specific TOSCA file?)

[tliron]

• Yes, I am are assuming description should be in about. It's basically an extension of description.
• These are entirely meta. platform could be something like "5G DU". The idea is to make room for an intended target environment, writ large or small. Note that I was indeed careful not to add an orchestrator key.
• I don't think there should be any rules about uniqueness. So, indeed, a bunch of scattered files might have been developed and owned by the same project, named here. We basically don't tell people how to use these, but of course they can provide the basis for a rich catalog.

[philippemerle]

Is it useful to add a new about keyname when we already have a metadata keyname? All these fields seem be useful for documenting a TOSCA file and seem to be useless for orchestration. So why not describing them as metadata? How could we be sure to not miss an important/interessing/useful about field? Do we need to let about open? For instance about could be a map with any YAML values, just like metadata. How will a user choice between defining an about field or defining a metadata?

[tliron]

Good question. about is indeed a kind of metadata. However, during our discussions we seemed to agree on a few things:

1. We didn't like reserving keys in metadata (as in TOSCA 1.3 [3.10.1.1]). It seemed to imply that orchestrators should take those special keys under consideration, and yet these were map keys, not keynames. If it was important enough to mention in the spec, why were these not real keynames?
2. We considered moving these keys to be top-level keynames, like description. But this seemed to "soil" the top level and felt inelegant. So I proposed organizing them under their own keyname, about.
3. We agreed that if we want to keep this feature then it has to be richer than just "template_name", "template_author", and "template version" (as in TOSCA 1.3). For one, it doesn't address profiles. But, then, it doesn't address a lot of things. My proposal here takes inspiration from other programming languages that allow for such descriptive metadata.

I also propose moving description to about, too (and actually having short and long versions), because it's metadata of exactly the same order. Note that the description keyname at the file level here works very differently from the rest of its usage in TOSCA, where it applies to entities. The TOSCA file is not an entity in any grammatical sense. It makes sense to me to treat that kind of metadata differently.

So, what is the goal of this feature? In my view:

1. It allows for standards-based cataloging of files, similarly to the metadata in CSAR files. A TOSCA IDE, a TOSCA catalog, etc., could now have a standard way to search for and present data about the TOSCA code. For large TOSCA codebases this could be helpful.
2. Moving this kind of cataloging function out of metadata, it allows metadata to be more clearly focused on orchestration. (Generally, I would like to see examples in the TOSCA spec of real-world usage of metadata. I can contribute a few.)

[pmjordan]

There are a number of existing standards available for metadata. Most seem to invoke the 'Dublin Core' or DCMI Using this standard would appear to provide formal specification of at least some of the attributes in the proposal including description, author/creator and licence. While the terms in that structure can be structured using RDF https://en.wikipedia.org/wiki/Resource_Description_Framework I don't think that complexity should put us off as the DCMI paragraph 2 of the DCMI Introduction section seems to specifically allow RDF to be disregarded in suituation such as TOSCA.