• Type: Task
    • Status: Open
    • Priority: Major
    • Resolution: Unresolved
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: Spec
    • Labels:


      The TOSCA TC currently has one normative document - the TOSCA v1.0 spec - and several non-normative documents (e.g. primer), but we are in the process of producing more normative material (base type definitions, simple profile / YAML spec) and have to decide how we are going to structure this editorial work. Below is a list of current or evolving documents as well some thoughts / suggestions on how we can structure editorial work. Discussion is highly welcome.

      (1) The only normative document so far is the v1.0 TOSCA spec for the TOSCA XML schema.
      This document has to be maintained as the v1.1 spec. In that document, we will have to do base editorial work like fixing bugs, handling review comments etc. Furthermore, we will have to update the XML spec for changes that we consider necessary in the v1.1 work.

      (2) The TOSCA Simple Profile / YAML document (currently being driven by Matt Rutkowski and others) will become the normative specification of TOSCA's YAML rendering. This document is being structured in a different approach (led by example) compared to (1) to increase consumability, but it will end up being a specification.

      (3) The TOSCA Base Types document will also be normative to have the set of base NodeTypes, RelationshipTypes etc. normatively written down. While working on the YAML examples during the last couple of weeks, it seemed convenient to use YAML to describe types. This way, it is often possible to have types defined in just a few lines that are easy to grasp. So a suggestion would be to use YAML for defining the TOSCA base types.
      For everyone who wants to see the XML/XSD counterparts, we could either have the respective rendering in the appendix, or refer to the YAML to XML translation rules (see below). I think that approach could help us to stick to simple structures (e.g. simple property data types) as opposed to having the full power of XML and XSD. Probably that will also help us to see if all we need can be expressed in the YAML rendering.

      Another option for addressing the XML audience would be to always include YAML and XML renderings of all NodeTypes etc. in the respective section (instead of putting the XML samples in the appendix). This could, however, make type definitions sections too long and distract from the key content. Furthermore, it seems like YAML is sufficient for a big audience.

      We will have to describe very clear rules for a two-way translation between the XML spec and the YAML spec (a rule can also be "XML construct ABC is not supported in the YAML spec/simple profile). The question here would be whether we make that part of the current XML spec or the new YAML spec. A suggestion would be to go with the latter option for now. If this makes the YAML document too big, we could make it a separate document.
      The goal of the "translation rules" definition should not be a generic XML <-> YAML translation rule set (this is much too broad and out of probably scope of the TOSCA TC work), but just the rules we need for TOSCA. An option would be to build a catalog of TOSCA constructs and describe how their XML and YAML renderings look like and map to each other.

      About the future of the XML and YAML renderings: at the moment, XML is the only normative rendering of TOSCA. YAML is evolving and will be equally important. Over time, we have to see which rendering gets broader adoption and whether one becomes more important than the other and what it means to maintain both renderings.

      About editors: Derek Palma and Thomas Spatzier are currently editors of (1) and should continue this work. It is suggested that both become co-editors of (2) and (3) to ensure consistency across all documents.
      For (2) and (3) we will need additional editors spread work across more shoulders. Matt Rutkowski is currently driving (2), so it is suggested that he becomes editor of (2); there can be more contributors of course.
      For the types system document (3), it would be ideal to involve many people from the TC to address different domains on a use case base.

      About formalities: for (1) we already have an official, formal TC work product. For (2) Matt is already switching to the official OASIS template. We will have to check whether we need to follow any process steps here.
      For (3) I think we still have to create the formal work product. I could take that TODO and come up with an initial skeleton document (title page, sections and TOC, maybe one sample type) and then really distribute work.




            • Assignee:
              thomas.spatzier Thomas Spatzier
              thomas.spatzier Thomas Spatzier
            • Watchers:
              0 Start watching this issue


              • Created: