1. TOSCA Namespaces Explained
Matt Rutkowski

2. 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.

3. 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.

4. 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:
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=" ” xmlns=
and Service Templates (as XML documents) would ALWAYS have (an implied) header with:
<<Service Template> xmlns= xmlns:tosca="  

5. 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

6. Illustrative: a TOSCA Orchestrator would have logically established the following
Global Namespace URIs with Namespace Prefix mapping
Fully Qualifed URI
Namespace Prefix
Default Namespace
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 [
Short Name
Classification
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

7. 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

8. 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.

9. 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

10. 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=" ” xmlns=
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

11. Backup

12. XML Names usage in XML Schema and documents with commentary
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.

13. Import vs. Include (XML commentary)
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.