JsonSchema does not define format=url, as requested by host parameters validation

[bojunehsu]

https://github.com/Azure/azure-openapi-validator/blob/main/docs/host-parameters-validation.md specifies: If a parameter matches belows, therefore it must be called 'endpoint' and be typed 'type:string, format:url'

However, url is not a defined format in JsonSchema. A previous request to add "url" as a JsonSchema format was rejected. Should we recommend users specify uri as format instead?

@mikekistler

[mikekistler]

The x-ms-parameterized-host extension is purely defined by autorest and is independent of JSON schema. OpenAPI uses format as a "hint" and does not restrict the values that can be specified. So IMHO there is nothing wrong with requiring format: url.

That said, I suppose we could allow either format: url or format: uri. The autorest docs say that these are equivalent:

https://github.com/Azure/autorest/blob/main/packages/libs/openapi/src/v3/formats.ts#L42

[bojunehsu]

On a related note, the current validator triggers a warning if format=uri even though uri is listed in https://github.com/Azure/autorest/blob/main/packages/libs/openapi/src/v3/formats.ts. Schema with type: string has unrecognized format: uri

Uri is also not listed in https://github.com/Azure/azure-openapi-validator/blob/main/docs/schema-type-and-format.md.

[jianyexi]

I think it's becuase 'url' is supported by autorest, there is a discussion about it, see https://github.com/Azure/azure-openapi-validator/issues/345#issuecomment-1180725859

[bojunehsu]

We need to be consistent between documentation and implementation. We should either remove "uri" from https://github.com/Azure/autorest/blob/main/packages/libs/openapi/src/v3/formats.ts (breaking change) or modify the linter to support it. Another option is to change the warning to say that "url" is preferred so that users are not confused.