The CRN pattern cannot be used because it is wrong

[mkrudele]

Which topic are you reporting about?

https://cloud.ibm.com/docs/api-handbook?topic=api-handbook-types#crn

What do you think needs to be updated?

The pattern proposed for the CRN in https://cloud.ibm.com/docs/api-handbook?topic=api-handbook-types#crn cannot be implemented because it would block legal CRNs. The last segment of the CRN, the resource does not prohibit any character (see the docs https://cloud.ibm.com/docs/account?topic=account-crn), including the :, so the pattern would block CRNs whose resource segment includes a text with : in addition to any other character not included in the group: ([A-Za-z0-9-._~!$&'()*+,;=@/]|%[0-9A-Z]{2}).

Anything else?

No response

[JohnStarich]

@mkrudele Can you please provide examples of valid and invalid CRNs with regard to the regular expression?

I'm having a tough time understanding how : can be used in a resource segment without it being encoded. : is the CRN segment separator, so segments shouldn't contain a literal :.

[mkrudele]

@JohnStarich I agree with you. My point is that that must be carefully documented in the https://cloud.ibm.com/docs/account?topic=account-crn. Below the extract I'm referring to:

////
resource-type, resource

The values of the resource-type and resource segments vary by service. A service is required to document their supported resource types segment and the format of the resource segment as part of their service metadata.

As an example, an image in the customer receipts container in an Object Storage service can have a resource-type segment of object and a resource value of CustomerReceipts/clientdinner.png.

The resource-type segment must be alphanumeric, lowercase, and no spaces or special characters other than '-'. A service can decide that the resource-type segment is optional, in which case it remains blank.
////

As you can read, there is no enforcement on the format of the resource field. What If I call a bucket my:bucket with spaces and the service decides to use the name of the bucket as resource? Not sure if the cos service is enforcing rules on the resource segment of a bucket.
In the past that was happening for schematics workspaces for example. Now Schematics is enforcing the workspace names to not contain several special characters and they are using the workspace name as resource crn field.
I'm afraid there are other teams not enforcing rules on the resource field. For example in GhoST we are getting resource_ids like endeft-o4a-event-notifications-key-ring:keyring:crn:v1:bluemix:public:kms:eu-gb:a/000111ffffffeeeaaaccc44466600012:60ccxxxx-zzzz-zzzz-xxxx-000000000000::.

[alexpit]

If I understand correctly, following this example:

What If I call a bucket my:bucket with spaces and the service decides to use the name of the bucket as resource? Not sure if the cos service is enforcing rules on the resource segment of a bucket.

There's a need to explicitly both inform & enforce the said CRN spec (a non-public specification: Cloud Resource Names, given that's what states: "It should be alphanumeric with no spaces or special characters other than '-'."), for fields that could potentially become CRN segments using said service API endpoint being documented.

And that, I assume, would be applicable to any other similar private specs that could be described similarly trivial, unless the rules of the spec (and validation tools) are available publicly.

[mkrudele]

@alexpit

There's a need to explicitly both inform & enforce the said CRN spec

Yes.

(a non-public specification: Cloud Resource Names,

The CRN specs are publicly available: https://cloud.ibm.com/docs/account?topic=account-crn

given that's what states: "It should be alphanumeric with no spaces or special characters other than '-'."), for fields that could potentially become CRN segments using said service API endpoint being documented.

The only missing segment in the documentation is resource. All the others are well documented.

[JohnStarich]

Thanks @mkrudele, I see it now. This may be a good source to help us get the doc updated for the resource format:

resource MUST be a be a GUID or a string encoded according to the URI syntax as described in RFC 3986 Uniform Resource Identifier (URI): Generic Syntax, Section 2. In particular the "/" character can be used to represent a hierarchical path.

– https://test.cloud.ibm.com/docs-internal/v2-system-architecture?topic=v2-system-architecture-cloud-resource-names-specification

[JohnStarich]

I think this needs to be moved to the IBM Cloud account docs repo. The API Handbook recommends a validation string that accepts this format.

account/crn.md

Lines 110 to 117 in ad93f98

	## resource-type, resource
	{: #resource-type-crn}
	The values of the `resource-type` and `resource` segments vary by service. A service is required to document their supported `resource types` segment and the format of the `resource` segment as part of their service metadata.
	As an example, an image in the customer receipts container in an Object Storage service can have a `resource-type` segment of `object` and a `resource` value of `CustomerReceipts/clientdinner.png`.
	The `resource-type` segment must be alphanumeric, lowercase, and no spaces or special characters other than '-'. A service can decide that the `resource-type` segment is optional, in which case it remains blank.

[swethaisrael]

Closing the issue as this is transferred to ibm-cloud-docs/api-handbook based on the comments

[JohnStarich]

This appears to be in error. This should be handled here in the account documentation. Please see #78 (comment)