Upper/lowercase Keywords - changing keywords

The keyword "must" appears in lowercase where it appears it should be uppercase "MUST."

"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:

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

The "must" in the first line appears to be the same type of "MUST" as appears in paragraph 1. Change to MUST.

*****

"3.2.3.1 Grammar

upper_bound: is a required integer value that denotes the upper boundary of the range. This value must be greater than lower_bound."

As a grammar definition, should be MUST.

*****

"3.2.4 TOSCA list type

Note that entries in a list for one property or parameter must be of the same type."

Requirement for members of a list, use MUST.

*****

"3.2.5 TOSCA map type

Note that entries in a map for one property or parameter must be of the same type."

Requirement for entries in a map or parameter, use MUST.

*****

"3.5.3.2 Additional Requirements

Property constraint clauses must be type compatible with the property definitions (of the same name) as defined on the target TOSCA entity that the clause would be applied against."

Requirement on property constraint clauses, use MUST.

*****

"3.7.2.2.3 Extended grammar with Property Assignments for the relationship’s Interfaces

node_type_name: represents the optional name of a TOSCA Node Type the associated named requirement can be fulfilled by. This must be a type that is compatible with the Node Type declared on the matching requirement (same symbolic name) the requirement’s Node Template is based upon."

Requirement on TOSCA Node Type, although expressed on a name attribute, use MUST.

*****

"3.7.3.3 Additional requirements

The source node template provided as a value on the copy keyname MUST NOT itself use the copy keyname (i.e., it must itself be a complete node template description and not copied from another node template)."

The header is a tip off as is the MUST NOT. The following must should be MUST.

*****

"3.7.4.2 Additional requirements

The source relationship template provided as a value on the copy keyname MUST NOT itself use the copy keyname (i.e., it must itself be a complete relationship template description and not copied from another relationship template)."

The "must" should be "MUST."

*****

"4.8.1.2 Parameters

Location value must be either a valid path e.g. ‘/etc/var/my_file’ or ‘LOCAL_FILE’."

Requirement for location values, thus MUST.

*****

"4.8.1.3.2 Example: Retrieving artifact as a local path :

In such implementation the tosca orchestrator must provide the wordpress.zip archive as a local path (example: /tmp/wordpress.zip) and will remove it after the operation is completed."

Although in an example, is this a requirement on the provision of local paths? There are only three mentions of "local path," two here and one under 4.8.1.3.3 Example: Retrieving artifact in a specified location.

This sounds and reads like a requirement that isn't expressed in normative text but in an example. I note it here without filing a separate issue.

*****

"4.8.1.3.3 Example: Retrieving artifact in a specified location:

In such implementation the tosca orchestrator must provide the wordpress.zip archive as a local path (example: C:/wpdata/wp.zip ) and will let it after the operation is completed."

Same questions as for: 4.8.1.3.2 Example: Retrieving artifact as a local path.

*****

"5.2.6.3 Additional requirements

A valid PortSpec must have at least one of the following properties: target, target_range, source or source_range."

Requirement on PortSpec and thus, MUST.

*****

"5.4.4.4 Additional requirements

Although both the port and ports properties are not required, one of port or ports must be provided in a valid Endpoint."

Awkward wording. Do you mean one port of many MUST have a valid Endpoint or that every specified port MUST have a valid Endpoint? In either case, it is MUST. Suggestion, drop the Although...required, - If that is a rule state it separately.

*****

"7.3.1 Connection initiation semantics

Endpoints at each end of the tosca.relationships.ConnectsTo must indicate identical connection initiation semantics."

Is that a requirement or are you trying to say that: "Endpoints at each end of a tosca.relationships.ConnectsTo have identical connection initiation semantics?"

I haven't scanned for use of the definite article (the) so a smoothing run across the text would not be amiss.

*****

"7.3.1.3 Peer-to-Peer

Endpoints specifying the Peer-to-Peer initiation semantic need not be related with a tosca.relationships.ConnectsTo relationship for the common case where the same set of component instances must communicate with each other. "

Even the lower case must is unneeded here: "...the same set of component instances communicate with each other.

*****

7.5.2.1 Properties

The order values must represent a positive, arithmetic progression that starts with 0 (e.g. 0, 1, 2, …, n). "

Requirement on order values, thus MUST.

*****

There are thirty-six uses of "should" in lowercase in sections 3-8, which are normative sections. I lacked the time to determine which, if any of them, merit SHOULD.

*****

"may" has even more uses than "should," for example:

"3.2.3.2 Keywords:

The following Keywords may be used in the TOSCA range type:"

Keywords? Clearly a MAY.

*****

"3.3.4 Network Name aliases

The following are recognized values that may be used as aliases to reference types of networks within an application model without knowing their actual name (or identifier) which may be assigned by the underlying Cloud platform at runtime."

Recognized values? MAY.

*****

"3.4.1 Required Keynames

The TOSCA metamodel includes complex types (e.g., Node Types, Relationship Types, Capability Types, Data Types, etc.) each of which include their own list of reserved keynames that are sometimes marked as required. These types may be used to derive other types."

Last sentence -> MAY

*****

"3.5.2.2 Additional Requirements

· If no operator is present for a simple scalar-value on a constraint clause, it SHALL be interpreted as being equivalent to having the “equal” operator provided; however, the “equal” operator may be used for clarity when expressing a constraint clause."

In requirements? Always "MAY"

*****

There are more than another 70 or so uses of may left to be checked.

*****

BTW, there are 48 cases of SHALL and 18 cases of MUST. Is there some reason for shifting control vocabularies back and forth?

Yes, I know that RFC2119 has both but being allowed to be inconsistent isn't the same thing as inconsistency being a good idea.

If you intended not difference in the usage, pick one or the other so readers can follow along more easily.