3. 知名 URI
3. 知名 URI
知名 URI (well-known URI) 是指路径分量以字符序列 /.well-known/ 开头的 URI [RFC3986], 前提是该方案被明确定义为支持知名 URI.
例如, 若某应用注册名称为 example, 则在 http://www.example.com/ 上对应的知名 URI 为 http://www.example.com/.well-known/example.
本规范更新 http [RFC7230] 与 https [RFC7230] 方案以支持知名 URI. 其他既有方案可采用适当流程更新其定义; 例如 [RFC8307] 对 ws 与 wss 方案这样做. 「统一资源标识符 (URI) 方案 (Uniform Resource Identifier (URI) Schemes)」注册表记录哪些方案支持知名 URI; 见第 5.2 节.
希望铸造 (mint) 新知名 URI 的应用 MUST 按照第 5.1 节的程序注册它们, 并满足以下要求.
注册名称 MUST 符合 [RFC3986] 中的 segment-nz 产生式. 这意味着不能包含 / 字符.
针对特定应用的注册名称 SHOULD 相应地精确; 不鼓励「霸占」通用术语. 例如, 若 Example 应用需要元数据的知名位置, 合适的注册名称可能是 example-metadata 或 example.com-metadata, 而不是 metadata.
注册至少应引用一份规范, 说明通过解引用知名 URI 所获得的格式及相关媒体类型 (media type), 以及该知名 URI 可配合使用的 URI 方案. 若未明确指定 URI 方案, 则假定使用 http 与 https.
通常, 应用会使用给定方案的默认端口; 若使用替代端口, 则 MUST 由相关应用明确说明.
注册 MAY 还包含其他信息, 例如可附加到知名 URI 的额外路径分量, 查询串与/或片段标识符的语法, 或协议相关细节 (例如 HTTP [RFC7231] 方法处理).
请注意, 本规范既不定义如何确定用于查找某应用知名 URI 的主机名, 也不定义通过解引用知名 URI 所发现元数据的范围; 二者均应由应用自身定义.
此外, 本规范未定义位于 /.well-known/ 的资源的格式或媒体类型, 客户端不应假定该位置存在资源.
知名 URI 根植于路径层次结构的顶层; 按定义, 在路径其他部分它们并非知名. 例如, /.well-known/example 是知名 URI, 而 /foo/.well-known/example 则不是.
关于知名位置的安全考量另见第 4 节.
3.1. 注册知名 URI
「知名 URI (Well-Known URIs)」注册表位于 https://www.iana.org/assignments/well-known-uris/. 可按该处的说明提交注册请求, 或向邮件列表 [email protected] 发送电子邮件.
注册请求至少包含以下信息:
URI 后缀 (URI suffix): 相对于 /.well-known/ 请求的知名 URI 名称; 例如 example.
变更控制方 (Change controller): 对 Standards Track RFC, 填写 「IETF」. 其他情况给出责任方名称. 亦可包含其他详情 (例如电子邮件地址, 主页 URI).
规范文档 (Specification document(s)): 引用规定该字段的文档, 最好包含可用于获取文档副本的 URI. 亦可指明相关章节, 但非必需.
状态 (Status): permanent 或 provisional 之一. 见下文指引.
相关信息 (Related information): 可选, 引用包含进一步相关信息的其他文档.
已注册值的一般要求见第 3 节.
由 Standards Track RFC 与其余开放标准 (按 [RFC2026] 第 7.1.1 节的含义) 定义的值状态为 permanent. 若专家与社区磋商后认为某值已在用, 其他值亦可注册为 permanent. 其余值应注册为 provisional.
若专家与社区磋商后认为某 provisional 条目未在使用, 专家可将其移除. 专家可将 provisional 条目的状态改为 permanent; 此时应考虑该值的使用广泛程度, 并事先与社区磋商.
上述 「与社区磋商」 指负责相关 URI 方案的人员. 一般会在相应工作组 (可能已结束) 的邮件列表上进行; 若无此类列表, 则在 [email protected] 上进行.
若专家认定某未注册的知名 URI 已广泛部署且否则不太可能及时注册, 第三方 (包括专家) 亦可注册知名 URI. 此类注册仍须满足已定义的要求, 包括必须引用规范.