Merge branch 'nisse/relative-os_pkg_url' into 'main'

Document that a descriptor's os_pkg_url may be relative, and how it is resolved

See merge request system-transparency/project/docs!49

content/docs/reference/os_package.md

@@ -115,6 +115,21 @@ certificates and signatures.
 The OS package URL field specifies where the zip archive can be downloaded using
 HTTP(S).  For example, `https://ospkg.example.org/debian-stable.zip`.
 
+If the URL is not absolute (i.e., not starting with scheme and host), it
+is resolved using the the URL of the descriptor file as the "base URI".
+E.g., if the descriptor file was downloaded from
+`https://ospkg.example.org/debian-stable.json`, and the OS package URL
+in the descriptor is `debian-stable.zip`, that is resolved to
+`https://ospkg.example.org/debian-stable.zip` before download. See
+[Reference Resolution](https://www.rfc-editor.org/rfc/rfc3986#section-5)
+for the precise resolution rules.
+
+**Compatibility note**: ST docs version v0.2.5 and earlier, part of the
+st-1.0.0 collection release, did not specify any "base URI" to use for
+resolving relative URLs, and hence implicitly required an absolute URL
+for the `os_pkg_url`. When compatibility with the st-1.0.0 components is
+desired, avoid using a relative URL in the descriptor.
+
 ### Example
 
 ```json