FOCUS #557: Preview - Refinement of FOCUS Columns Normative Requirements #664
Conversation
| * AvailabilityZone is RECOMMENDED to be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports deploying resources or services within an *availability zone*. | ||
| * If present, the column MUST conform to the following additional requirements: | ||
| * AvailabilityZone MUST be of type String. | ||
| * AvailabilityZone MUST conform to [String Handling](#stringhandling) requirements. |
There was a problem hiding this comment.
| * AvailabilityZone MUST conform to [String Handling](#stringhandling) requirements. |
Discussed in Dec 10 TF1. Propose postponing adding such requirements until lower-hanging fruit of consistency is collected.
There was a problem hiding this comment.
I must have missed something. Why is linking attributes contentious?
There was a problem hiding this comment.
Talking to Irena - she suggested postponing this due to provider conformance concerns.
There was a problem hiding this comment.
I suggest we discuss this in the TF-1 meeting. This sheet can serve as the basis for our discussion.
specification/columns/regionid.md
Outdated
| * RegionId MUST be of type String. | ||
| * RegionId MUST conform to [String Handling](#stringhandling) requirements. | ||
| * RegionId MUST NOT be null when a *resource* or *service* is operated in or managed from a distinct region by the Provider. | ||
| * RegionId MAY be null when a *resource* or *service* is not restricted to an isolated geographic area. |
There was a problem hiding this comment.
in the previous line, with a MUST NOT be NULL condition - we say 'operated in or managed from a distinct region'
in this line where it MAY be NULL we say 'not restricted to an isolated geographical area'.
would the 2nd line be clearer as follows:
| * RegionId MAY be null when a *resource* or *service* is not restricted to an isolated geographic area. | |
| * RegionId MAY be null when a *resource* or *service* is not operated in or managed from a distinct region. |
There was a problem hiding this comment.
Current version (using identical wording in both requirements):
- RegionId MUST NOT be null when a resource or service is operated in or managed from a distinct region.
- RegionId MAY be null when a resource or service is operated in or managed from a distinct region.
Suggestions:
- Add 'region' as an additional term in the glossary.
| * AvailabilityZone is RECOMMENDED to be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports deploying resources or services within an *availability zone*. | ||
| * If present, the column MUST conform to the following additional requirements: | ||
| * AvailabilityZone MUST be of type String. | ||
| * AvailabilityZone MUST conform to [String Handling](#stringhandling) requirements. |
There was a problem hiding this comment.
I must have missed something. Why is linking attributes contentious?
| The AvailabilityZone column adheres to the following requirements: | ||
|
|
||
| * AvailabilityZone is RECOMMENDED to be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports deploying resources or services within an *availability zone*. | ||
| * If present, the column adheres to the following additional requirements: |
There was a problem hiding this comment.
nit: Personally, I would rather not have this line and keep all requirements at the root level. The requirements are all valid whether the column is present or not, so I'm not sure what the value of nesting these requirements is.
| @@ -2,6 +2,17 @@ | |||
|
|
|||
| The [*billed cost*](#glossary:billed-cost) represents a charge serving as the basis for invoicing, inclusive of the impacts of all reduced rates and discounts while excluding the [*amortization*](#glossary:amortization) of relevant purchases (one-time or recurring) paid to cover future eligible charges. This cost is denominated in the [Billing Currency](#billingcurrency). The Billed Cost is commonly used to perform FinOps capabilities that require cash-basis accounting such as cost allocation, budgeting, and invoice reconciliation. | |||
|
|
|||
| --- | |||
There was a problem hiding this comment.
nit: Do we have a requirement that these lines be here? Do we require them to have specific spacing before/after? I don't mind them. I would just ask that they have empty lines before and after to align to existing markdown linting rules. (Although, I don't think we've implemented any yet.)
There was a problem hiding this comment.
These lines are just temporary separators surrounding the candidate versions of the normative requirements (helping us to more easily spot the before/after differences).
specification/columns/chargeclass.md
Outdated
| * ChargeClass MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset). | ||
| * ChargeClass MUST be of type String. | ||
| * ChargeClass MUST be null when the row does not represent a correction or when it represents a correction within the current *billing period*. | ||
| * When the row represents a correction to a previously invoiced *billing period*, the following applies: |
There was a problem hiding this comment.
Should this be "If"? Also aligning to a previous suggestion...
| * When the row represents a correction to a previously invoiced *billing period*, the following applies: | |
| * If the row represents a correction to a previously invoiced *billing period*, the column adheres to the following additional requirements: |
| * ServiceSubcategory MUST NOT be null. | ||
| * ServiceSubcategory MUST be one of the allowed values. | ||
| * ServiceSubcategory MUST have one and only one parent ServiceCategory as specified in the allowed values below. | ||
| * Though a given *service* can have multiple purposes, each *service* SHOULD have one and only one ServiceSubcategory that best aligns with its primary purpose |
There was a problem hiding this comment.
This is a confusing requirement. We have allowed values, so it should be a MUST. If this is context on the allowed values requirement, I would rather see it nested under that and remove the "SHOULD".
There was a problem hiding this comment.
In addition to Michael's comment,
- I suggest moving this requirement to the ServiceName column definition, as it is one of the normative requirements for ServiceName.
- Furthermore, considering that ServiceSubcategory is currently RECOMMENDED, I propose adding two explicit and easily verifiable requirements to the ServiceName column: one defining its relationship with ServiceSubcategory, and another for its relationship with ServiceCategory.
- Additionally, I would like to establish a consistent pattern for column relationship-related requirements.
PREFERRED PATTERN:
- XY MUST be associated with one and only one parent MN ...
SkuPriceId:
BEFORE:
- SkuPriceId MUST be associated with one and only one SkuId, except ...
AFTER:
- SkuPriceId MUST be associated with one and only one parent SkuId, except ...
ServiceCategory:
The Service Category is the highest-level classification of a service based on the core function of the service. Each service should have one and only one category that best aligns with its primary purpose.
ServiceSubcategory:
BEFORE:
The Service Subcategory is a secondary classification of the Service Category for a service based on its core function.
...
- ServiceSubcategory MUST have one and only one parent ServiceCategory as specified in the allowed values below.
- Though a given service can have multiple purposes, each service SHOULD have one and only one ServiceSubcategory that best aligns with its primary purpose
AFTER:
The Service Subcategory is a secondary classification of the Service Category for a service based on its core function.
...
- ServiceSubcategory MUST be associated with one and only one parent ServiceCategory as specified in the allowed values below.
ServiceName (for discussion in a meeting):
BEFORE:
A service represents an offering that can be purchased from a provider...
...
The Service Name is a display name for the offering that was purchased...
AFTER:
A service represents an offering that can be purchased from a provider...
...
The Service Name is a display name for the offering that was purchased...
...
- Each service SHOULD be associated with one and only one parent ServiceCategory that best aligns with its primary purpose.
- Each service SHOULD be associated with one and only one parent ServiceSubcategory that best aligns with its primary purpose if ServiceSubcategory is present.
…e-reqs-update-preview
…ng applies -> the column adheres to the following additional requirements:
…hange mistakenly applied to the original Normative Requirement
… adheres to...' -> 'the XY adheres to...'
…e-reqs-update-preview
This PR serves solely as a preview and discussion base and is not intended for merging into the working draft.
It includes both the original version and the candidate version of normative requirements across all existing columns to facilitate a clear comparison (before/after) for review and feedback.
The goal of this PR is to provide a comprehensive context for discussing potential updates to normative requirements across the specification. It aims to ensure that the impact of proposed changes on all column definitions is thoroughly reviewed and debated.
Please use this PR as a collaborative tool, keeping in mind that it is not finalized content and should not be merged into the working draft.