TOSCA Namespaces Explained Matt Rutkowski 2017-11-02

Let’s review the essential guidance on TOSCA Namespacing 3.1.2 TOSCA Namespacing in TOSCA Service Templates  In the TOSCA Simple Profile, TOSCA Service Templates MUST always have, as the first line of YAML, the keyword “tosca_definitions_version” with an associated TOSCA Namespace Alias value. This single line accomplishes the following: Establishes the TOSCA Simple Profile Specification version whose grammar MUST be used to parse and interpret the contents for the remainder of the TOSCA Service Template. Establishes the default TOSCA Namespace URI and Namespace Prefix for all types found in the document that are not explicitly namespaced. Automatically imports (without the use of an explicit import statement) the normative type definitions (e.g., Node, Relationship, Capability, Artifact, etc.) that are associated with the TOSCA Simple Profile Specification the TOSCA Namespace Alias value identifies. Associates the TOSCA Namespace URI and Namespace Prefix to the automatically imported TOSCA type definitions.

Orchestrator Processing of “tosca_definitions_version” keyword Establishes the TOSCA Simple Profile Specification version whose grammar MUST be used to parse and interpret the contents for the remainder of the TOSCA Service Template. Sample TOSCA Service Template tosca_definitions_version: tosca_simple_yaml_1_2  … Based upon encountering the Namespace alias “tosca_simple_yaml_1_2” a TOSCA Orchestrator would logically: Establish a Parser/Validator for TOSCA v1.2 YAML grammar, which is able to: Enforce Grammar and Schema compliance i.e., not only a valid YAML document, but also compliant to schema including: reserving all TOSCA keynames and validating hierarchical structure: e.g., “topology_template”, “node_templates”, “type”, ”capabilities”, “requirements”, “properties”, ”attributes”, etc. Enforce v1.2 Specification requirement compliance Including enforcing all spec. “Requirements” clauses in prose/text which uses RFC2119 language i.e., SHALL, MUST, etc.

Orchestrator Processing of “tosca_definitions_version” keyword Establishes the default TOSCA Namespace URI and Namespace Prefix for all types found in the document that are not explicitly namespaced. The Namespace alias “tosca_simple_yaml_1_2” would also cause a TOSCA Orchestrator to logically: Establish the TOSCA Namespace URI as the default Namespace for the template TOSCA Namespace URI: http://docs.oasis-open.org/tosca/ns/simple/yaml/1.2 Note: URIs are not required to be an active URL which hyperlinks to a schema document Binds the (reserved) Namespace Prefix: ”tosca” to the TOSCA Namespace URI For use in Service Templates to optionally Qualify local Type names used for establishing a clear prefix that can optionally be used with all TOSCA Type (short or full) name references for unambiguous type “lookup” with within the document context and be viewed as being equivalent to the Namespace URI for the Service Template (Instance) document context IF this were XML instead of YAML (and it is not), AND we had a TOSCA v1.2 XML Schema Definition (XSD) file THEN: the TOSCA Namespace URI would be the “target” and “default” namespace for all v1.2 Types defined in the XSD file: <xs:schema targetNamespace=" http://docs.oasis-open.org/tosca/ns/simple/yaml/1.2 ” xmlns=http://docs.oasis-open.org/tosca/ns/simple/yaml/1.2> and Service Templates (as XML documents) would ALWAYS have (an implied) header with: <<Service Template> xmlns=http://docs.oasis-open.org/tosca/ns/simple/yaml/1.2 xmlns:tosca="http://docs.oasis-open.org/tosca/ns/simple/yaml/1.2">  

Orchestrator Processing of “tosca_definitions_version” keyword Automatically imports (without the use of an explicit import statement) the normative type definitions (e.g., Node, Relationship, Capability, Artifact, etc.) that are associated with the TOSCA Simple Profile Specification the TOSCA Namespace Alias value identifies. The Namespace alias “tosca_simple_yaml_1_2” would also cause a TOSCA Orchestrator to: Import all TOSCA v1.2 Types Qualified by the TOSCA Namespace URI for use in the current Service Template (document instance), including Node, Relationship, Capability, Interface, Data, Artifact, Group, and Policy Types Assign “Shortname” to each

Illustrative: a TOSCA Orchestrator would have logically established the following Global Namespace URIs with Namespace Prefix mapping Fully Qualifed URI Namespace Prefix Default Namespace http://open.org/tosca/ns/simple/yaml/1.2/ tosca True <others to be added via “import”> Global Namespace – with sampling of v1.2 Types into v1.2 TOSCA Namespace Owning Namespace URI Full Name [http://docs.oasis-open.org/tosca/ns/simple/yaml/1.2/] Short Name Classification http://open.org/tosca/ns/simple/yaml/1.2/ tosca.nodes.Compute Compute nodes “ tosca.nodes.SoftwareComponent SoftwareComponent tosca.nodes.Storage.ObjectStorage ObjectStorage … tosca.relationships.HostedOn HostedOn relationships tosca.relationships.ConnectsTo ConenctsTo tosca.capabilities.Endpoint Endpoint capabilities tosca.capabilities.Container Container capabiltiies tosca.datatypes.Credential Credential datatypes tosca.datatypes.json json

Profiles & Conformance What is intended Approved, TOSCA Namespace URI - define a TOSCA-approved Namespace URI for the Profile’s Types that matches spec. version i.e., for default/target namespace Extensibility via Profile Types - define new Types needed to model the subject area for the Profile These Types would be bound to the TOSCA approved Namespace URI for the Profile Simplified Import – allow profile types to be imported “on-top” of TOSCA Simple Profile base types Ideally, “import” of a Profile’s Types should be accomplished with one (1) line of YAML Namespace Prefix: possible a reserved Namespace Prefix for the Profile Note: TOSCA base profile version compatibility is an issue to discuss What is not intended No new Grammar - Profiles are not allowed to define new grammar Should not define new “keywords” for TOSCA entities Profile WGs should submit uses cases to the Simple Profile WG that express needs in the base profile Limited ability to describe additional Requirements (prose) on individual Types e.g., describe special treatment of property/attribute values Perhaps “constraints” grammar is not expressive enough? or one Property value depends on another? Note: the Profile WG should try to submit uses cases to Simple Profile WG when they find limitations that could be fixed via the core grammar

Issues & Notes (1) Do we need a TOSCA Schema document? WG has never produced an official schema (definition) file as YAML has no (defacto) standard for this assumes developers are able to create a union of Types defined in Spec. Pros: Might clarify Type Namespacing relative the TOSCA Namespace URI (as the “target” namespace) Cons: There is no YAML schema, we would have to define our own Schema format (not ideal) IMO: Cons outweigh Pros as we do not want to invent/solve YAML issues, add to complexity for what should be a simpler concept. We need to explain/illustrate better for implementers. Do we have Namespace collision for the TOSCA Type shortname “Compute”? i.e, tosca.nodes.Compute, tosca.capabilities.Compute TBD: Pros / Cons Yes, if we wish to provide clearer rules for constructing a global namespace using the rules we have outlined in spec. already No, if we add additional “rules” to force Orchestrators to be “context” aware when resolving ambiguous type names that is, within the TOSCA Grammar it SHOULD be clear where a Node Type name vs. a Capability Type name is expected Notes: we have repeatedly ack’ed that in TOSCA there is a relationship between Node Types (as resource representations) vs. Capability Types which are references to the “essential” capabilities of same said resource.

Issues & Notes (2) Do Profiles of TOSCA Simple Profile in YAML ONLY have Type definitions? Do they need to define a Namespace URI? Yes, if they follow TOSCA Simple Profile naming convention they need: A unique Namespace URI (to be used as the target/default namespace for all the Types) to qualify their Type names Do they need to define a Namespace Prefix? Yes or No (TBD) No: if a multi-line “import” statement is used, then the author can assign a local “prefix” themselves. imports: - file: <file_URI> repository: <repository_name> namespace_uri: <definition_namespace_uri> namespace_prefix: <definition_namespace_prefix> Yes: if we follow TOSCA Simple Profile guidance and wish to SIMPLIFY authoring Service Templates That is, it would be TOSCA-like to allow “import” of a reserved Namespace alias (much like “tosca_simple_yaml_1_2”) for a Profile imports: - tosca_some_profile_alias_1_1 which could automatically assign a defined ”prefix” for the Types defined in the “imported” Profile

Issues & Notes (3) What are we missing, in general, to effectively namespace user-defined Types? We have to ack. that a Service Template allows both a “schema” (Type) and document instance (Template) Using XML terms we are missing an ability for a Service Template author to define a target Namespace URI and default Namespace for local, unprefixed declarations <xs:schema targetNamespace=" http://docs.oasis-open.org/tosca/ns/simple/yaml/1.2 ” xmlns=http://docs.oasis-open.org/tosca/ns/simple/yaml/1.2> Can a v1.2 Tosca template import a TOSCA v1.1 template? i.e. Can we handle mixed TOSCA Types in different URI Namespaces? Note: Namespace Prefix “tosca” would be “overloaded” Would need to describe how “import” should rewrite prefix (or expand to full version-specific URI)? Can Profiles that reference TOSCA v1.1 be imported into a TOSCA v1.2 template? Can’t just use “tosca” prefix Concern: newer version of spec. uses a name that might “hijack” a name defined elsewhere Implicit: an implicit namespace SHOULD be created for local document (Service Template) for locally defined types by the Orchestrator. TBD

Backup

XML Names usage in XML Schema and documents with commentary https://stackoverflow.com/questions/7190572/targetnamespace-and-xmlns-without-prefix-what-is-the-difference targetNamespace is an XML Schema "artifact"; its purpose: to indicate what particular XML namespace the schema file describes. xmlns - because the XML Schema is an XML document, it is then possible to define a default XML namespace for the XML file itself (this is what xmlns attribute does); the implications are multiple: authoring, and composition. For example, one does not have to use a prefix for the items defined in the schema, that are later on referenced elsewhere in the same file (e.g. a global simpleType used as a type for an attribute or element). Many XML Schema authors consider this as a "best practice"... so you're on the right track. In terms of XSD, the targetNamespace prescribes the namespace part of a qualified name of a schema component, which includes elements, attributes, groups and attribute groups, and simple and complex types. Some of the qualified names defined in an XSD (elements and attributes) are "directly" used by an XML instance document. Others, such as for types, can be referenced through the xsi:type attribute in instance XML documents. The rest (groups, attribute groups) are there to facilitate schema composition (through references). I'm also of opinion that (in general) people come at designing XSD from two angles: to match an existing XML. In this case, if your XML uses namespaces, for each of the namespaces used, you'll end up with an XSD schema element with a matching targetNamespace attribute. pure modeling. You then think of targetNamespace similar to an UML package, or database schema, or a Java package, or a .NET namespace, and all it means in this case. Fundamentally it is a mechanism to avoid naming collisions; nonetheless, it is also a mechanism to partition models in subject areas, etc.

Import vs. Include (XML commentary) https://stackoverflow.com/questions/2357943/whats-the-difference-between-xsdinclude-and-xsdimport The fundamental difference between include and import is that you must use import to refer to declarations or definitions that are in a different target namespace include to refer to declarations or definitions that are (or will be) in the same target namespace.